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PREFACE 

This manual describes the use of the RT-11 Operating System. It 
assumes the reader is familiar with computer software fundamentals and 
has had some exposure to assembly language programs. The section 
"Additional and Reference Material" later in this Preface lists 
documents that may prove helpful in reviewing those areas. The 
Glossary provides definitions of technical terms used in the manual. 

The user who is unfamiliar with RT-11 should first read those chapters 
of interest (see "Chapter Summary" below) to become familiar with 
system conventions. Having gained familiarity with RT-11, the user 
can then reread the manual for specific information. 

Chapter Summary 

Chapter 1 discusses system hardware and software requirements. It 
describes general system operations and lists specific components 
available under RT-11. 

Chapter 2 introduces the user to system conventions and monitor/memory 
layout. It describes in detail the keyboard commands for controlling 
jobs and implementing user programs. 

Chapt 

MACRO 

ed 

de 

ass 



lapters 3 through 8 describe the system utility programs EDIT, PIP, 
iCRO, LINK, LIBR, and ODT, respectively. These programs (a text 
litor, file transfer program, assembler, linker, librarian, and 
bugging program) aid the user in creating text files and producing 
■sembly-language programs. 

Chapter 9, which describes programmed requests, is of particular 
interest to the experienced programmer. It describes call sequences 
that allow the user to access system monitor services from within 
assembly-language programs. 

Chapters 10 and 11 describe the 8K Assembler and EXPAND programs, 
respectively. These programs are useful in RT-11 installations with 
minimum memory configurations. 

Chapter 12 describes the BATCH command language for RT-11. In BATCH 
mode, the RT-11 system can be left to run unattended for long periods 
of time. 

The appendixes summarize the contents of the manual and describe 
additional system utility programs that can be used for extended 
system operations. These programs include SRCCOM (a source file 
comparison program) ; FILEX (a file translation program that allows 
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transfer of files between RT-11 and other DIGITAL operating systems) ; 
PATCH and PATCHO (patching programs) ; DUMP (a file dump program) ; 
and SYSLIB (a library of programmed requests for FORTRAN users) . 



Version History 

The current RT-11 system (monitor) is Version 
component (monitors and utilities) is 
identification number in the form Vxx-xx. 
numbers for V2C are listed in the RT-1 
(DEC-11-0RNRA-A-D) . To determine whether the 
component is in use, examine its identificat 
with the list. (The procedure for examin 
varies. Most system programs provide a speci 
the version number when an output listing is 
approiate chapter or appendix of this manual 



2C (V2C) . Each system 
assigned a software 

Current. identification 
1 System Release Notes 

correct, version of a 
ion number and compare it 
ing the version number 
al command; others print 
requested. Consult the 
for each component.) 



NOTE 

Throughout this manual, any references 
to V2 or V2B of RT-11 will pertain also 
to V2C. The RT-11 System Release Notes 
contain a comprehensive list of 
differences between V2C and previous 
versions of RT-11 (V2B, V2 , VI). 



Change bars and asterisks in the outermost margins of the manual are 
used to denote changes made to the text since the Version 2 release 
(DEC-11-0RUGA-B-D) . The date July 1975 in the lower outside corner of 
a page indicates that the page was changed as a result of a 
release-independent update that occurred in July, 1975. The date 
January 1976 in the lower outside corner of the page indicates that 
the page was changed specifically as a result of the V2C update. 

The user who is already familiar with the Version 2B RT-11 System 
Reference Manual (DEC-11-0RUGA-C-D,DN1) should first read the RT-11 
System Release Notes document to note the major differences between 
V2B and V2C, and then read those pages of the RT-11 System Reference 
Manual that have changed as a result of the V2C update (identified By 
the date January 1976) . The RT-11 System Generation Manua l 



(DEC-11-0RGMA-A-D) should also be read if 
devices and features is required. 



customization for special 



The user who is familiar with only the Version 2 RT-11 System 
Reference Manual (DEC-11-0RUGA-B-D) should read the following in 



addition to those items mentioned in the preceding paragraph: 



Chapter 
Chapter 
Chapter 
Chapter 
Appendix 



2 

3 

9 

12 

H 



Appendix 



(System Communication) 
(Text Editor) 
(Programmed Requests) 
(BATCH) 

(F/B Programming 
And Device Handlers) 
(SYSLIB) 



Tables 2-2, 2-3, and 2-5 
Section 3.6.5.6 
Sections 9.1 and 9.1.3.6 

Entire Chapter 

Sections H.2.4 and H.2.5 
Entire Appendix 



Finally, the user familiar with only the Version 1 RT-11 System 
Reference Manual (DEC-11-0RUGA-A-D) should read this entire manual 
with these exceptions: 
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Chapter 3 (Text Editor) - note Section 3.7 

Chapter 5 (MACRO Assembler) - note Section 5.7 

Chapter 8 (ODT) - note restrictions in Section 

8.1 

Chapter 10 (EXPAND) 

Chapter 11 (ASEMBL) 

Appendix L (PATCH) 

While knowledge of Versions 2 and 2B is sufficient for use of V2C, 
knowledge of Version 1 is not; the user with Version 1 knowledge only 
should carefully read the manual. 

Additional and Reference Material 

The following manuals provide an introduction to the PDP-11 computer 
family and the basic PDP-11 instruction set: 

PDP-11 Paper Tape Software Programming Handbook ** 

(DEC-11-XPTSA-B-D) 
PDP-11 Processor Handbook * 
PDP-11 Peripherals Handbook * 

The following manual provides an introduction to the use of RT-11 by 
presenting a simple demonstration of basic operating procedures: 

RT-11 System Generation Manual * (DEC-11-ORGMA-A-D) 

These manuals describe the capabilities of the optional high-level 
language components: 

BASIC/RT-11 Language Reference Manual ** (DEC-11-LBACA-D-D) 
PDP-11 FORTRAN Language Reference Manual ** (DEC-11-LFLRA-B-D) 
RT-11/RSTS/E FORTRAN IV User's Guide ** (DEC-11-LRRUA-A-D) 

Summaries of the features provided by each language appear in this 
manual in Appendixes F and G respectively. 

Two PDP-11 system manuals are helpful when using FILEX (Appendix J) to 
convert programs between DOS, RSTS, and RT-11 formats: 

PDP-11 Resource Sharing Time-Sharing System User's Guide ** 

(DEC-11-ORSUA-D-D) 
DOS/BATCH Handbook ** (DEC-11-ODBHA-A-D) 

Users of display hardware may wish to refer to the appropriate 
hardware manual: 

GT40/42 User's Guide *** (39H150) 

GT44 User 's Guide *** (39H250) 

VT11 Graphic Display Processor Manual *** (79H650) 

DECscope User's Manual *** (EK-VT50-OP) 

The experienced programmer will want to read the following manual: 

RT-11 Software Support Manual * (DEC-11-ORPGA-B-D) 



♦Included in the RT-11 Software Kit 

**May be ordered from the DIGITAL Software Distribution Center 

***May be ordered from DIGITAL Communication Services 
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Consult the following for a list of all manuals available in the RT-11 
software documentation set: 

RT-11 Documentation Directory * (DEC-11-0RDDA-A-D) 

D ocumentation Conventions 

Conventions used throughout this manual include the following: 

1. Actual computer output is used in examples wherever possible,. 
When necessary, computer output is underlined to 
differentiate from user responses. 

2. A line feed (character or key) is represented in the text as 
<LF>; a carriage return (character or key) is represented as 
<CR>. Unless otherwise indicated, all commands and command 
strings are terminated by a carriage return. 

3. Terminal, console terminal, and teleprinter are general terms 
used throughout all RT-11 documentation to represent any 
terminal device, including DECwriters, displays, and 
Teletypes****. RP02 is a generic term used to represent both 
the RP11C/RP02 and RP11E/RPR02 disks. 

4. Several characters in system commands are produced by typing 
a combination of keys concurrently; for example, the CTRL 
key is held down while typing an to produce a command which 
causes suppression of teleprinter output. Key combinations 
such as this are documented as CTRL 0, CTRL C, SHIFT N, and 
so forth. 



*Included in the RT-11 Software Kit 

****Teletype is a registered trademark of the Teletype Corporation. 
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CHAPTER 1 
RT-11 OVERVIEW 



RT-11 is a single-user programming and operating system designed for 
the PDP-11 series of computers. This system permits the use of a wide 
range of peripherals and up to 28K of either solid state or core 
memory (hereafter referred to as memory) . 

RT-11 provides two operating environments: Single-Job operation, and 
a powerful Foreground/Background (F/B) capability (1) . 

Single-Job operation allows only one program to reside in memory at 
any time; execution of the program continues until either it is 
completed or it is physically interrupted by the user at the 
console. 

In a Foreground/Background environment, two independent programs may 
reside in memory. The foreground program is given priority and 
executes until it relinquishes control to the background program; the 
background program is allowed to execute until control is again 
required by the foreground program, and so on. This sharing of system 
resources greatly increases the efficiency of processor usage. 

To handle both operating environments, RT-11 offers two completely 
compatible and versatile monitors (Single-job and F/B) ; either monitor 
provides complete user control of the system from the console terminal 
keyboard. Monitor commands which allow the user to direct single- job, 
foreground, and background operations are described in Chapter 2. 

In addition to the monitor facilities, RT-11 offers a full complement 
of system programs; these allow program development using high level 
languages such as FORTRAN IV and BASIC or assembly language (MACRO or 
EXPAND/ASEMBL) . System programs are summarized in Section 1.2 and are 
discussed in detail in individual chapters and appendixes of this 
manual. 



(1) The uses and advantages of each environment are outlined later in 
this chapter. 
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1.1 PROGRAM DEVELOPMENT 

Computer systems such as RT-11 are often used extensively for program 
development. The programmer makes use of the programming "tools" 
available on his system to develop programs which will perform 
functions specific to his needs. The number and type of "tools" 
available on any given system depend on a good many factors — the size 
of the system, its application and its cost, to name a few. Most 
DIGITAL systems, however, provide several basic program development 
aids: these generally include an editor, assembler, linker, debugger, 
and often a librarian; a high level language (such as FORTRAN IV or 
BASIC) is also usually available. 

An editor is used to create and modify textual material. Text may be 
the lines of code which make up a source program written in some 
programming language, or it may be data; text may be reports, or 
memos, or in fact may consist of any subject matter the user wishes. 
In this respect using an editor is analogous to using a 
typewriter — the user sits at a keyboard and types text. But the 
advantages of an editor far exceed those of a typewriter because once 
text has been created, it can be modified, relocated, replaced, 
merged, or deleted — all by means of simple editing commands. When the 
user is satisfied with his text, he can save it on a storage device 
where it is available for later reference. 

If the editor is used for the purpose of writing a source program, 
development does not stop with the creation of this program. Since 
the computer cannot understand any language but machine language 
(which is a set of binary command codes) , an intermediary program is 
necessary which will convert source code into the instructions the 
computer can execute. This is the function of an assembler. 

The assembler accepts alphanumeric representations of PDP-11 coding 
instructions (i.e., mnemonics), interprets the code, and produces as 
output the appropriate object code. The user can direct the assembler 
to generate a listing of both the source code and binary output, as 
well as more specific listings which are helpful during the program 
debugging process. In addition, the assembler is capable of detecting 
certain common coding errors and of issuing appropriate warnings. 

The output produced by the assembler is called object output because 
it is composed of object (or binary) code. On PDP-11 systems, the 
object output is called a module and contains the user's source 
program in the binary language which is acceptable to a PDP-11 
computer . 

Source programs may be complete and functional by themselves; 
however, some programs are written in such a way that they must be 
used in conjunction with other programs (or modules) in order to form 
a complete and logical flow of instructions. For this reason the 
object code produced by the assembler must be relocatable— that is, 
assignment of memory locations must be deferred until the code is 
combined with all other necessary object modules. It is the purpose 
of linker to perform this relocation. 

The linker combines and relocates separately assembled object 
programs. The output produced by the linker consists of a load 
module, which is the final linked program ready for execution. The 
user can, at his option, request a load map which displays all 
addresses assigned by the linker. 
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Very rarely is a program created which does not contain at least one 
unintentional error, either in the logic of the program or in its 
coding. Errors may be discovered by the programmer while he is 
editing his program, or the assembler may find errors during the 
assembly process and inform the programmer by means of error codes. 
The linker may also catch certain errors and issue appropriate 
messages. Often, however, it is not until execution that the user 
discovers his program is not working properly. Programming errors may 
be extremely difficult to find, and for this reason a debugging tool 
is usually available to aid the programmer in determining the cause of 
his error. 

A debugging program allows the user to interactively control the 
execution of his program. With it, he can examine the contents of 
individual locations, search for specific bit patterns, set designated 
stopping points during execution, change the contents of locations, 
continue execution, and test the results, all without the need of 
re-editing and re-assembling. 

When programs are successfully written and executed, they may be 
useful to other programmers. Often routines which are common to many 
programs (such as I/O routines) or sections of code which are used 
over and over again, are more useful if they are placed in a library 
where they can be retrieved by any interested user. A librarian 
provides such a service by allowing creation of a library file. Once 
created, the library can be expanded, updated, or listed. 

High level languages simplify the programmer's work by providing an 
alternate means of writing a source program other than assembly 
language mnemonics. Generally, high level languages are easy to 
learn — a single command may cause the computer to perform many machine 
language instructions. The user does not need to know about the 
mechanics of the computer to use a high level language. In addition, 
some high level languages (like BASIC) offer a special immediate mode 
which allows the user to solve equations and formulas as though he 
were using a calculator. Assembling and linking are done 
automatically so that the user can concentrate on solving the problem 
rather than using the system. 

These are a few of the programming tools offered by most computer 
systems. The next section summarizes specific programming aids 
available to the user of RT-11. 



1.2 SYSTEM SOFTWARE COMPONENTS 

The following is a brief summary of the RT-11 system programs : 

1. The Text Editor (EDIT, described in Chapter 3) is used to 
create or modify source files for use as input to language 
processing programs such as the assembler or FORTRAN. EDIT 
contains powerful text manipulation commands for quick and 
easy editing of a text file. EDIT also allows use of a VTll 
display processor (such as the GT44) , if one is part of the 
hardware configuration (see Section 1.3). 

2. The MACRO Assembler (Chapter 5) brings the capabilities of 
macros to the RT-11 system with 12K (or more) memory. 
(Macros are instructions in a source or command language 

which are equivalent to a specified sequence of machine 
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instructions or commands.) The assembler accepts source files 
written in the MACRO language and generates a relocatable 
object module to be processed by the Linker before loading 
and execution. Cross reference listings of assembled 
programs may be produced using CREF in conjunction with the 
MACRO Assembler. 

3. EXPAND (Chapter 10) is used in an 8K F/B job area or 8K 
systems (or in larger systems with programs of great size) to 
expand macros in an assembly language program into macro-free 
source code, thus allowing the program to be assembled in 8K 
using ASEMBL. 

4. ASEMBL (Chapter 11) is an assembler designed for use in an 8K 
RT-11 system, an 8K F/B job area, or larger systems where 
symbol table space is a factor. ASEMBL is a subset of 
MACRO-11 with more limited features. (CREF is not available 
under ASEMBL.) 

5. The Linker (LINK, described in Chapter 6) fixes (i.e., makes 
absolute) the values of relocatable symbols and converts the 
relocatable object modules of compiled or assembled programs 
and subroutines into a load module which can be loaded and 
executed by RT-11. LINK can automatically search library 
files for specified modules and entry points; it can produce 
a load map (which lists the assigned absolute addresses) and 
can provide automatic overlay capabilities to very large 
programs. The Linker can also produce files suitable for 
running in the foreground. 

6. The Librarian (LIBR, see Chapter 7) allows the user to create 
and maintain his own library of functions and routines. 
These routines are stored on a random access device as 
library files, where they can be referenced by the Linker. 

7. The Peripheral Interchange Program (PIP, see Chapter 4) is 
the RT-11 file maintenance and utility program. It is used 
to transfer files between all devices which are part of the 
RT-11 system, to rename or delete files, and to obtain 
directory listings. 

8. SRCCOM (Source Compare, described in Appendix K) allows the 
user to perform a character-by-character comparison of two or 
more text files. Differences can be listed in an output file 
or directly on the line printer or terminal, thus providing a 
fast method of determining, for example, if all edits to a 
file have been correctly made. 

9. FILEX (Appendix J) allows file transfers to occur between 
DECtapes used under the DECsystem-10 or PDP-11 RSTS system, 
and DECtape and disk used under the DOS/BATCH system, and any 
RT-11 device. 

10. The PATCH utility program (Appendix L) is used to make minor 
modifications to memory image files (output files produced by 
the Linker) ; it is used on files which do or do not have 
overlays. PATCHO (Appendix M) is used to make minor 
modifications to files in object format (output files 
produced by the FORTRAN compiler and the Librarian, or MACRO 
and ASEMBL assemblers). 
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11. ODT (On-line Debugging Technique, described in Chapter 8) 
aids in debugging assembled and linked object programs. It 
can print the contents of specified locations, execute all or 
part of the object program, single step through the object 
program, and search the object program for bit patterns. 

12. DUMP (Appendix I) is used to print for examination all or any 
part of a file in octal words, octal bytes, ASCII and/or 
RAD50 characters (see Chapter 5) . 

13. BATCH (Chapter 12) is a complete job control language that 
allows RT-11 to operate unattended. The BATCH stream may be 
composed of RT-11 monitor commands or system-independent 
BATCH jobs (jobs that will run on any DIGITAL system 
supporting the BATCH standard; currently RT-11 and RSX-llD) . 
BATCH streams can be executed under the Single -Job Monitor 
or in the background under the F/B Monitor. 

14. The RT-11 FORTRAN System Subroutine Library (SYSLIB, Appendix 
0) is a collection of FORTRAN callable routines that make the 
programmed requests and various utility functions available 
to the FORTRAN programmer. SYSLIB also provides a complete 
string manipulation package and two-word integer package for 
RT-11 FORTRAN. 

BASIC and FORTRAN IV are two high level languages available under 
RT-11. Summaries of their language features and commands are provided 
in Appendixes F and G of this manual. 



1.3 SYSTEM HARDWARE COMPONENTS 

The minimum RT-11 system (that is, one that does not use the F/B 
capability) requires a PDP-11 series computer with at least 8K of 
memory, a random-access device, and a console terminal. The F/B 
capability requires at least 16K of memory and a line frequency clock. 
For specific hardware/software interdependent requirements, refer to 
the RT-11 System Release Notes . 

Devices supported by RT-11 are listed in Table 1-1. The third 
(middle) column lists devices for which support is initially provided 
in the system as distributed; these devices can be used with no 
modification (to either the monitor tables or the handlers) necessary. 
The devices in the fourth column are supported after simple 
modifications to the monitor tables or handlers. The system 
customization section of the RT-11 System Generation Manual describes 
how to make these modifications. The fifth column lists devices for 
which no support is provided, but which may be interfaced by the user. 
Currently, the KS64 disk is the only device in this category, and 
instructions for its interface are provided in the RT-11 Software 
Support Manual . 

Consult the RT-11 System Generation Manua l for modifications that may 
be made to existing system devices (for example, varying the baud rate 
of a terminal) . 
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Table 1-1 
RT-11 Hardware Components 



Category 



DISK 

DECpack 

Cartridge 
Fixed- head 



Removable 

Pack 
Diskette 



DECTAPE 



MAGTAPE 



CASSETTE 



HIGH-SPEED 
PAPER TAPE 
READER/PUNCH 



LINE PRINTER 



CARD READER 



TERMINAL 



DISPLAY 



Controller 



PROCESSOR 



CLOCK 



RK11 

RF11 
RC11 
RH11 

RP11 

RX11 

TC11 

TM11/TMA11 

RH11 

TA11 

PC11 
PR11 



LS11 
LV11 
LP11 



CR11 
CM11 

DL11 



VT11 



System-Installed 
Devices 



RK05 

RS11 

RJS03 

RP02 

RX01 

TU56 

TU10,TS03 
TJU16 

TU60 

PC11 (both) 

PR11 (reader only) 

LS11, LA180 
LV11 (printer only) 
all LP11 controxled 
printers 



LT33, LT35 
LA30P, LA36, 
VT50, VT52, 
VT05 

VR14-L,VR17-L 



Devices Re- 
quiring System 
Modification 



KW11-L 



RJS04 

RP03 

RX01 (second 
controller) 



CR11 
CM11 



LA30S 



User-Installed 
Devices 



RS64 
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RT-11 operates in environments ranging from 8K to 28K words of memory. 
Reconfiguration for different memory sizes is unnecessary—the same 
system device operates on any PDP-11 processor with 8K to 28K of 
memory and makes use of all memory available. 



1.4 USING THE RT-11 SYSTEM 

As mentioned earlier in the chapter, the RT-11 system offers two 
complete operating environments. Each is controlled by a single user 
from the console terminal keyboard by means of an appropriate 
monitor — Single-Job or Foreground /Background. Both monitors are 
completely compatible and allow full user interaction with all 
features which are a part of the operating environment in use. 

The choice of which environment to use, and, consequently, which 
monitor to run, depends upon the needs of the user. The next two 
sections provide information useful in determining which monitor is 
more suitable for certain applications. 



1.4.1 RT-11 Single-Job Monitor 

The RT-11 Single- Job Monitor provides a single- user, single-program 
system which can operate in as little as 8K of memory. Since the 
Single-Job Monitor itself requires approximately one-half the memory 
space needed by the Foreground/Background Monitor, this system is 
ideal for extensive program development work; a much larger area of 
memory is available for the user program and its buffers and tables. 
Programs requiring extremely high data rates are best run in the 
Single- Job environment, since interrupts can be serviced at a much 
higher rate. 

All system programs (listed in Section 1.2) can be used under the 
Single- Job Monitor, and many of the features of the 
Foreground/Background Monitor (i.e., KMON commands and programmed 
requests not used to control foreground jobs) are supported. 

In effect, the Single-Job Monitor is much smaller and slightly faster 
than the Foreground/Background Monitor; it can best be used when 
program size is the important factor. 



1.4.2 RT-11 Foreground/Background Monitor 

Quite often the central processor of a computer system may spend a 
large percentage of time waiting for some external event to occur, the 
most common event being the completion of an I/O transfer (this is 
particularly true of real time jobs). Many users would like to take 
advantage of this unused capacity to accomplish other lower-priority 
tasks such as further program development or complex data analysis. 
The Foreground/Background system provides this capability. 

In a Foreground/Background system the foreground job is the 
time-critical, on-line job, and is given top priority; whenever 
possible the processor runs the foreground job. However, when the 
foreground job reaches a state in which no more processing can be done 
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until some external event occurs, the monitor will try to run the 
lower priority background job, The background job then runs until the 
foreground job is again in a runnable state, at which point the 
processor will interrupt the background job and resume the foreground 
job. 

In general, the RT-11 Foreground/Background System is designed to 
allow a time-critical job to run in the foreground, while the; 
background does non-time-critical jobs, such as program development,, 
(All RT-11 system programs run as the background job in a F/B system.) 
Thus, the user can run FORTRAN, BASIC, MACRO, etc. in the background 
while the foreground may be collecting data and storing and/or 
analyzing it. 

Most user programs written for an RT-11 System can be linked (using 
the Linker described in Chapter 6) to run as the foreground job,, 
There are a few coding restrictions, and these are explained in 
Appendix H, F/B Programming and Device Handlers. A foreground program 
has access to all of the features available to the background job 
(opening and closing files, reading and writing data, etc.). In 
addition, the F/B System gives the user the ability to set timer 
routines, suspend and resume F/B jobs, and send data and messages 
between the two jobs. 



1.4.3 Facilities Available Only in RT-11 F/B 

As mentioned previously, RT-11 F/B allows the user to write and 
execute two independent programs. Some features which are available 
only to the F/B user include : 

1. Mark Time — This facility allows user programs to set clock 
timers to run for specified amounts of time. When the timer 
runs out, a routine specified by the user is entered. There 
may be as many mark time requests as desired, providing 
system queue space is reserved (see .QSET, Chapter 9). 

2. Timed Wait — This feature allows the user program to "sleep"' 
until the specified time increment elapses. Typically, a 
program may need to sample data every few seconds or even 
minutes. While the program is idle, the other job can run. 
The timed wait accomplishes this; when the time has elapsed, 
the issuing job is again runnable (see .TWAIT, Chapter 9). 

3. Send Data/Receive Data — It is possible, under RT-11 F/B, to 
have the foreground and background programs communicate with 
one another. This is accomplished with the send/receive data 
functions. Using this facility, one program sends messages 
(or data) in variable size blocks to the other job. This can 

be used, for example, to pass data from a foreground 
collection program directly to a background analysis program 
(see .SDAT/.RCVD, Chapter 9). 



CHAPTER 2 
SYSTEM COMMUNICATION 



The monitor is the hub of RT-11 system communications; it provides 
access to system and user programs, performs input and output 
functions, and enables control of background and foreground jobs. 

The user communicates with the monitor through programmed requests and 
keyboard commands. The keyboard commands (described in Section 2.7) 
are used to load and run programs, start or restart programs at 
specific addresses, modify the contents of memory, and assign and 
deassign alternate device names. 

Programmed requests (described in detail in Chapter 9) are source 
program instructions which pass arguments to the monitor and request 
monitor services. These instructions allow user assembly language 
programs to utilize the available monitor features. 



2.1 START PROCEDURE 

After the system has been built (see the RT-11 System Generation 
Manual ) , the monitor can be loaded into memory from disk or DECtape as 

follows : 

1. Press HALT. 

2. Mount the system device on unit (or the appropriate unit if 
a unit other than is to be used) . 

3. WRITE PROTECT the system unit. 

If the hardware configuration includes a hardware bootstrap capable of 
booting the system device, 

1. Set the switch register to the appropriate address and press 
LOAD ADRS. 

2. If a second address is required, set the switch register to 
that address. 

3. Press START. 
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If a hardware bootstrap is not available, or if an RK disk unit 
other than is to be used as the system device, one of the following 
bootstraps must be entered manually using the Switch Register. First 
set the Switch Register to 1000 and press the LOAD ADRS switch. Then 
set the Switch Register to the first value shown for the appropriate 
bootstrap and raise the DEPosit switch. Continue depositing the 
values shown. 



DECtape 



Disk 





(RK11 


,RK05) than Unit 0) 




(RF11) 


(RJS03/4) 


(RP11/RP02) 


(RX11/RX01) 


12700 


12700 


12700 




12700 


12705 


12705 


12702 


177344 


177406 


177406 




177466 


172044 


176716 


1002n7** 


12710 


12710 


12760 




5010 


12745 


12715 


12701 


177400 


177400 


xxxxxx * 




5040 


177400 


177400 


177170 


12740 


12740 


4 




12740 


12745 


12745 


130211 


4002 


5 


12700 




177400 


71 


5 


1776 


5710 


105710 


177406 




12740 


32715 


105715 


112703 


100376 


100376 


12710 




5 


100200 


100376 


7 


12710 


5007 


177400 




105710 


1775 


5007 


10100 


3 




12740 




100376 


100762 




10220 


105710 




5 




5007 


5007 




402 


100376 




105710 










12710 


12710 




100376 










1 


5 




5007 










6203 


105710 
















103402 


100376 




* xxxxxx 


= 20000 


for 


unit 1 


112711 


5007 






40000 
60000 
100000 
120000 
140000 
160000 


for 
for 
for 
for 
for 
for 


unit 2 
unit 3 
unit 4 
unit 5 
unit 6 
unit 7 






111023 
30211 
1776 
100756 
103766 
105711 
100771 






























5000 
















22710 






I 


240 












** n - 4 


for unit 


1347 












6 


for unit 1 | 


122702 
















247 
















5500 


















5007 



When all the values have been entered, set the switches 
press the LOAD ADRS and START switches. 



to 1000 and 



The monitor loads into memory and prints one of the following 
identification messages followed by a dot (.) on the terminal: 

RT-11SJ V02C-XX 
RT-11FB V02C-XX 

The message printed indicates which monitor (Single-Job or F/B) has 
been loaded; the user may determine which is to be loaded during the 

system build operation. 

After the message has printed, the system device should be WRITE 
ENABLED. The monitor is ready to accept keyboard commands. 
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To bring up an alternate monitor while under control of the one 
currently running (in this case, F/B) , run PIP to perform the following 
operations: 

1. Preserve the running monitor by renaming it to yyyyyy.SYS 
(the actual name yyyyyy is not significant, although it is 
suggested that yyMNSJ for Single-Job and yyMNFB for Fore- 
ground/Background be used to be consistent with system con- 
ventions; yy in this case represents the disk type) : 

, R PIP 

*RK0:RKMNFB. SYS-RK0 : MGNI TR. SVS/R/V 

7REBQQT? 

2. Rename the desired monitor to MONITR.SYS: 

*RK0:MONITR. SVS-RK9 : RKMNSJ. SVS/R/V 

7REB00T? 

3. Write the new bootstrap from the new MONITR.SYS file 

(using the PIP /U option; A is a dummy filename, which 
must be present in the command line) : 

*RK8:fl = RK0 :M0NI TR. SVS/U 



4. Reboot the system. 
*RK0:/O 
RT-11SJ V82C-02 



Refer to the RT-11 System Generation Manual for an example of switching 
monitors . 
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2.2 SYSTEM CONVENTIONS 



Special character commands, file naming procedures and other 
conventions that are standard for the RT-11 system are described in 
this section. The user should be familiar with these conventions 
before running the system. 



2.2.1 Data Formats 

The RT-11 system makes use of five types of data formats: ASCII, 
object, memory image, relocatable image, and load image. 

Files in ASCII format conform to the American National Standard Code 
for Information Interchange, in which each character is represented by 
a 7-bit code. Files in ASCII format include program source files 
created by the Editor, listing and map files created by various system 
programs, and data files consisting of alphanumeric characters. A 
chart containing ASCII character codes appears in Appendix C. 

Files in object format consist of data and PDP-11 machine language 
code. Object files are those output by the assembler or FORTRAN 
compiler and are used as input to the Linker. 

The Linker can output files in memory image format (.SAV), relocatable 
image format (.REL), or load image format (.LDA). 

A memory image file (.SAV) is a 'picture' of what memory will look 
like when a program is loaded. The file itself requires the same 
number of disk blocks as the corresponding number of 256-word memory 
blocks. 

A relocatable image file (.REL) is one which can be run in the 
foreground. It differs from a memory image file in that the file is 
linked as though its bottom address were 0. When the program is called 
(using the monitor FRUN command) , the file is relocated as it is 
loaded into memory. (A memory image file requires no such 
relocation.) 
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A load image (or .LDA) file may be produced for compatibility with the 
PDP-11 Paper Tape System and is loaded by the absolute binary loader. 
LDA files can be loaded and executed in stand-alone environments 
without relocation. 



2.2.2 Prompting Characters 

The following table summarizes the characters typed by RT-11 to 
indicate to the user either that the system is awaiting user response 
or to specify which job (foreground or background) is producing 
output J 



Table 2-1 
Prompting Characters 



Character 


Meaning 


• 
* 

t 
> 


The Keyboard Monitor is waiting for a command (see 
Section 2.3.2) . 

The Command String Interpreter is waiting for a 
command string specification as explained in 
Sections 2.3.3 and 2.5. 

When the console terminal is being used as an 
input file, the uparrow prompts the user to enter 
information from the keyboard. If the input is 
entered under EDIT or BASIC (or any program that 
accepts input in special terminal mode as 
described in Chapter 9) , the characters entered 
are not echoed. Typing a CTRL Z marks the 
end-of-file. 

The > character is used (under the F/B Monitor and 
only if a foreground job is active) to identify 
which job, foreground or background, is producing 
the output currently appearing on the console 
terminal. Each time output from the background 
job is to appear, B> is printed first, followed by 
the output. If the foreground job is to print 
output, F> is typed first. B> and F> are also 
printed as a result of the CTRL B and CTRL F 
commands described in Table 2-4. 



2.2.3 Physical Device Names 

Devices are referenced by means of a standard two-character device 
name. Table 2-2 lists each name and its related device. If no unit 
number is specified for devices which have more than one unit, unit 
is assumed. 
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Table 2-2 
Permanent Device Names 



Permanent Name 


I/O Device 


CR: 


Card Reader (CRll/CMll) . 


CTn: 


TA11 cassette (n is the unit number, or 1) . 


DK: 


The default logical storage device for all files. 
DK is initially the same as SY: (see below) , but the 
assignment (as a logical device name) can be changed 
with the ASSIGN Command (Section 2.7.2.4). 


DKn: 


The specified unit of the same device type as DK. 


DPn: 


RP02 disk (n is an integer in the range 0-7) . 


DSn: 


RJS03/4 fixed-head disks (n is in the range 0-7) . 


DTn: 


DEC tape n, where n is a unit number (an integer in 
the range to 7, inclusive). 


DXn: 


RX01 Floppy disk (n is or 1) . 


LP: 


Line printer. 


MMn: 


TJU16 magtape (n is in the range 0-7) . 


MTn: 


TM11 (industry compatible) magtape (n is an integer 
between and 7, inclusive). 


PP: 


High-speed paper tape punch. 


PR: 


High-speed paper tape reader. 


RF: 


RF11 fixed-head disk drive. 


RKn: 


RK disk cartridge drive n (n is in the range to 
7 inclusive) . 


SY: 


System device; the device and unit from which the 
system is bootstrapped. (RT-11 allows 

bootstrapping from any kk unit; refer to Section 
2.1.) The assignment as a logical device name car. 
be changed with the ASSIGN command (Section 2.7.2.4). 


SYn: 


The specified unit of the same device type as that 
from which the system was bootstrapped. 


TT: 


Terminal keyboard and printer. 



In addition to the fixed names shown in Table 2-2, devices can be 
assigned logical names. A logical name takes precedence over a 
physical name and thus provides device independence. With this 
feature a program that is coded to use a specific device does not need 
to be rewritten if the device is unavailable. Refer to Section 
2.7.2.4 for instructions on assigning logical names to devices. 



2.2.4 File Names and Extensions 



Files are referenced symbolically by a name of one to six alphanumeric 
characters followed, optionally, by a period and an extension of up to 
three alphanumeric characters. (Excess characters in a filename may 
cause an error message.) The extension to a filename generally 
indicates the format of a file. It is a good practice to conform to 
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the standard filename extensions for RT-11. If an extension is not 
specified for an input or output file, most system programs assign 
appropriate default extensions. Table 2-3 lists the standard 
extensions used in RT-11, 

Table 2-3 
File Name Extensions 



Extension 



Meaning 



.BAD 



.BAK 

.BAS 
.BAT 

.CTL 

.CTT 

.DAT 
.DIR 
.DMP 
.FOR 
.LDA 

.LLD 
.LOG 
.LST 

.MAC 

.MAP 
.OBJ 

.PAL 

.REL 

.SAV 

.SOU 
,SYS 



Files with bad (unreadable) blocks; this 
extension can be assigned by the user 
whenever bad areas occur on a device. The 
.BAD extension makes the file permanent in 
that area, preventing other files from using 
it and consequently becoming unreadable. 

Editor backup file. 

BASIC source file (BASIC input) . 
BATCH command file. 



BATCH control file generated by the 
BATCH compiler. 

BATCH internal temporary file. 

BASIC or FORTRAN data file. 
Directory listing file 
DUMP output file. 

FORTRAN IV source file (FORTRAN input) 

binary file (optional 



Absolute 
output) . 



Linker 



Library listing file. 
BATCH log file. 

Listing file (MACRO or FORTRAN output) . 

MACRO or EXPAND source file (MACRO, EXPAND, 
SRCCOM input) . 

Map file (Linker output) . 

Relocatable binary file (MACRO, ASEMBL,, 
FORTRAN IV output, Linker input, LIBR input 
and output) . 

Output file of EXPAND (the MACRO expander 
program) , input file of ASEMBL. 

Foreground job relocatable image (Linker 
output, default for monitor FRUN command) . 

Memory image or SAVE file; default for R„ 
RUN, SAVE and GET Keyboard Monitor commands j 
also default for output of Linker. 

Temporary source file generated by BATCH. 
System files and handlers. 
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If a filename with a blank extension is to be used in a command line 
in which a default extension is assumed (by either the monitor or a 
system program) , the user must insert a period after the filename to 
indicate that there is no extension. For example, to run the file 
TEST, type: 

.RUN TEST. 

If the period after the filename is not given, the monitor assumes the 
„SAV extension and attempts to run a file named TEST.SAV. 



2.2.5 Device Structures 

RT-11 devices are categorized by the physical structure of the device 
and the way in which the device allows information to be processed. 

All RT-11 devices are either random-access or sequential-access devices. 
Random-access devices allow blocks of data to be processed in a random 
order — that is, independent of the data's physical location on the 
device or its location relative to any other information. All disks 
and DECtape fall into this category. Random-access devices are some- 
times also called block-replaceable devices, because individual data 
blocks can be manipulated (rewritten) without affecting other data 
blocks on the device. Sequential-access devices require that data be 
processed sequentially; the order of processing data must be the same 
as the physical order of the data. RT-11 devices that are considered 
sequential devices are magtape, cassette, paper tape, card reader, 
line printer, and terminal. 

File- structured devices are those devices that allow the storage of 
data under assigned filenames. RT-11 devices that are file-structured 
include all disks, DECtape, magtape, and cassette. Nonf ile-structured 
devices, on the other hand, are those used to contain a single logical 
collection of data. These devices are used generally for reading and 
listing information, and include line printer, card reader, terminal, 
and paper tape devices. 

Finally, file-structured devices are classified further as RT-11 direc - 
tory-structured devices if they provide a standard RT-11 directory at 
the. beginning of the device (the standard RT-11 directory is defined 
in the RT-11 Software Support Manual ) . The directory contains informa- 
tion about all files stored on the device and is updated each time a 
file is moved, added, or deleted from the device. RT-11 directory- 
structured devices include all disks and DECtapes. NonRT-11 directory- 
structured devices are file-structured devices that do not have the 
standard RT-11 directory structure at their beginning. For example, 
some devices, such as magtape and cassette, have directory-type infor- 
mation stored at the beginning of each file; the device must be read 
sequentially to obtain all information about all files. 

It is possible to interface a device to the RT-11 system with a user- 
defined directory structure; procedures are explained in the RT-11 
Software Support Manual . 
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2.3 MONITOR SOFTWARE COMPONENTS 

The main RT-11 monitor software components are: 

Resident Monitor (RMON) 

Keyboard Monitor (KMON) 

User Service Routine (USR) and Command String Interpreter (CSI) 

Device Handlers 

The reader may find Figure 2-1 helpful while reading the following 
descriptions . 

2.3.1 Resident Monitor (RMON) 

The Resident Monitor is the only permanently memory-resident part of 
RT-11. The programmed requests for all services of RT-11 are handled 
by RMON. RMON also contains the console terminal service, error 
processor, system device handler, EMT processor, and system tables. 

2.3.2 Keyboard Monitor (KMON) 

The Keyboard Monitor provides communication between the user at the 
console and the RT-11 system. Monitor commands allow the user to 
assign logical names to devices, run programs, load device handlers, 
and control F/B operations. A dot at the left margin of the console 
terminal page indicates that the Keyboard Monitor is in memory and is 
waiting for a user command. 

2.3.3 User Service Routine (USR) 

The User Service Routine provides support for the RT-11 file 
structure. It loads device handlers, opens files for read or write 
operations, deletes and renames files, and creates new files. The 
Command String Interpreter (the use of which is described in Section 
2.5) is part of the USR and can be accessed by any program to 
interpret device and file I/O information. 
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2.3.4 Device Handlers 

Device handlers for the RT-11 system perform the actual transfer of 
data to and from peripheral devices. New handlers can be added to the 
system as files on the system device and can be interfaced to the 
system by modifying a few monitor tables (see the RT-11 Software 
Support Manual, DEC-11-0RPGA-B-D for instructions on how to interface 
a new handler to the RT-11 monitor) . 



2.4 GENERAL MEMORY LAYOUT 

When the RT-11 System is first bootstrapped from the system device, 
memory is arranged as shown in the left diagram of Figure 2-1 (this is 
the case for either the Single-Job or Foreground/Background Monitor, 
since no foreground job exists yet) . The background job is the RT-11 
module KMON. 

When an RT-11 foreground job is initiated (via the monitor FRUN 
command. Section 2.7.5.1) , room is created for the foreground job to 
be loaded by decreasing the amount of space available to the 
background job. The memory maps in Figure 2-1 illustrate the system 
layout before and after a foreground job is loaded. (Refer also to 
Chapter 6, Section 6.5.) 





RMON 




USR 




KMON 


BEFORE 

LOADING 

THE 

FOREGROUND 

JOB 





HIGH 
ADDRESSES 



RMON 



HANDLERS 



FJOB 



USR 



KMON 



AFTER 

LOADING 

THE 

FOREGROUND 

JOB 



Figure 2-1 
RT-11 System Memory Maps 

As shown in the figures, the process of loading a foreground job 
requires that the USR and KMON be physically moved. Once a foreground 
job is running, it is possible to communicate with either the 
background or foreground job via special commands (described in 
Section 2.7). All of the terminal support functions described in 
Section 2.6 are available under both the Single-job and F/B Monitors. 

In addition to FRUN, other monitor commands can alter the memory map; 
these are LOAD, UNLOAD, GT ON, and GT OFF. LOAD causes device 
handlers to be made resident \intil an UNLOAD command is performed. 
UNLOAD deletes handlers which have been loaded. GT ON and GT OFF 
cause terminal service to utilize the VT-11 display hardware. Figure 
2-2 illustrates the placement of display modules and device handlers 
in memory following the GT 0N„ LOAD, and FRUN commands: 
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RMON 


HIC 
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GT40 (GT ON GT OFF) 




HANDLERS 




F JOB 


;h 


USR 


ADDRESSES 


KMON 





Figure 2-2 
RT-11 Memory Map (GT40) 

RT-11 maintains a free memory list to manage memory. Thus, when a 
handler is unloaded, the space the handler occupied is returned to the 
free memory list and is reclaimed by the background. 



2.4.1 Component Sizes 

Following are the approximate sizes (in words) of the 
RT-11, Version 2C (sizes reflect RK) . 



components for 



RMON 

USR 

KMON 



F/B 

3575(10) 
2050(10) 
1800(10) 



Single- job 

1703(10) 
2050(10) 
1540(10) 



In the F/B system, the background area must always be large enough to 
hold KMON and USR (3.9K words). The following list indicates the total 
space available for the loaded device handlers, the foreground job, 
and the display handler. Note that the low memory area from 0-477 is 
never used for executable programs. (These sizes also allow room for 
the 3.5K RMON) . 



Machine size (words) 

16K 
24K 

28K 



Space available (words) 

8.5K 
16. 5K 
20. 5K 



With the Single- Job Monitor, RMON requires only 1.67K. The following 
list shows the amount of space available to users with the Single-Job 
Monitor : 
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Machine size (words) 

8K 
16K 
24K 
28K 



Program space available (words) 

6K 
14K 
22K 
26K 



2.5 ENTERING COMMAND INFORMATION 

Once either monitor has been loaded and a system program started, the 
user must enter the appropriate command information before any opera- 
tion can be performed. 

In most cases, the Command String Interpreter immediately prints an 
asterisk at the left margin. The user must then type a command string 
in the general format: 

OUTPUT= INPUT/SWITCH 

(A few system programs — EDIT, PATCH, PATCHO -- require that this com- 
mand information be entered in a slightly different format. Complete 
instructions are provided in the appropriate chapter.) 

In all cases, the format for OUTPUT is: 

devtfilnam.ext [n] ,. . .dev: filnam.ext [n] 

INPUT is: 

dev:filnam.ext,. . .dev: filnam.ext 
and SWITCH is: 

/s:oval or /sldval 



where : 

dev: 



filnam.ext 



[n] 



/s:oval or 
/sldval 
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in each case is an optional two to three-character 
name from Table 2-2 whose usage conforms to the 
NOTE below. 

in each case is the name of a file (consisting of 
one to six alphanumeric characters followed 
optionally by a dot and a zero to three-character 
extension) . As many as three output and six input 
files may be allowed. 

is an optional declaration of the number of blocks 
(n) desired for an output file, n is a decimal 
number (<65,535) enclosed in square brackets 
immediately following the output filnam.ext to 
which it applies. 

is one or more optional switches whose functions 
vary according to the program in use (refer to the 
switch option table in the appropriate chapter) . 
oval is either an octal number or one to three 
alphanumeric characters (the first of which must 
be alphabetic) which will be converted to radix- 50 
(see Section 5.5.4 of the MACRO chapter), dval is 
a decimal value preceded by an exclamation point. 
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Throughout this manual, the /s:oval construction 
is used; however, the /sldval format is always 
valid. Generally, these switches and their 
associated values, if any, should follow the 
device and filename to which they apply. 

If the same switch is to be repeated several times 
with different values (e.g., /L:MEB/L:TTM/L:CND to 
MACRO) the line may be abbreviated as 
/L:MEB:TTM:CND; octal, RAD50, and decimal values 
may be mixed. 

if required, is a delimiter that separates the out- 
put and input fields. The < sign may be used in 
place of the = sign. The separator can be omitted 
entirely if there are no output files. 



NOTE 

As illustrated in the general format of 
a command line, the command line 
consists of an output list, a separator 

(= or <) , and an input list. 
Omission of a device specification in 
either the input or output list is han- 
dled as follows: 



DK: is assumed if the first file in a 
list has no explicit device. DK (or the 
device associated with the first file) 
is default until another device is 
indicated; that device then becomes 
default until a new one is used, and so 
on. If the following command is 
entered, for example, to MACRO: 

*DT1: FIRST. OBJ, LP:=TfiSK. 1, RK1 : TftSK. 2, TASK. 2 

it is interpreted as though all devices 
had been indicated as follows: 

*DT1 .FIRST. OBJ, LP : =DK : TftSK. 1, RK1 : TftSK. 2, RK1 : TftSK. 2 



2.6 KEYBOARD COMMUNICATION (KMON) 

Special function keys and keyboard commands allow the user to 

communicate with the RT-11 monitor and allocate system 
resources, manipulate memory images, start programs, and use 
foreground/background services. 

The special functions of certain terminal keys used for communication 
with the Keyboard Monitor are explained in Table 2-4. Note that in the 
F/B system, the Keyboard Monitor always runs as a background job. 

CTRL commands are entered by holding the CTRL key down while typina 
the appropriate letter. YFJ-ng 
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Table 2-4 
Special Function Keys 



Key 



CTRL A 



CTRL B 



Function 



CTRL C 



CTRL E 



CTRL F 



Valid when the monitor GT ON command has been typed and 
the display is in use. The command does not echo on 
the terminal. It is used after a CTRL S has been typed 
to effectively page output. Console output is 
permitted to resume until the screen is completely 
filled; text previously displayed is scrolled upward 
off the screen. CTRL A has no special meaning if GT ON 
is not in effect or if a SET TTY NOPAGE command has 
been given (see Section 2.7.2.8). 

Under the F/B Monitor echoes B> on the terminal (unless 
output is already coming from the background job) and 
causes all keyboard input to be directed to the 
background job. At least one line of output will be 
taken from the background job (the foreground job has 
priority, and control will revert to it if it has 
output) . All typed input will be directed to the 
background job until control is redirected to the 
foreground job (via CTRL F) . CTRL B has no special 
meaning when used under a Single-Job Monitor or when a 
SET TTY NOFB command has been issued (see Section 
2.7.2.8). 

CTRL C echoes as "C on the terminal and is used to 
interrupt program execution and return control to the 
keyboard monitor. If the program to be interrupted is 
waiting for terminal input, or is using the TT handler 
for input, typing one CTRL C is sufficient to interrupt 
execution; in all other cases, two CTRL Cs are neces- 
sary. Note that under the F/B Monitor, the job which is 
currently receiving input will be the job that is stopped 
(determined by whether a CTRL F or CTRL B was most re- 
cently typed) . To ensure that the command is directed 
to the proper job, type CTRL B or CTRL F before typing 
CTRL C. 

Valid when the monitor GT ON command has been typed and 
the display is in use. The command does not echo on 
the terminal, but causes all terminal output to appear 
on both the display screen and the console terminal 
simultaneously. A second CTRL E disables consoles 
terminal output. CTRL E has no special meaning if 
GT ON is not in effect. 

Under the F/B Monitor echoes F> on the terminal and 
instructs that all keyboard input be directed to the 
foreground job and all output be taken from the 
foreground job. If no foreground job exists, F? is 
printed and control is directed to the background job, 
Otherwise, control remains with the foreground job 
until redirected to the background job (via CTRL B) or 
until the foreground job terminates. CTRL F has no 
special meaning when used under a Single- Job Monitor, 
or when a SET TTY NOFB command has been used (see 

Section 2.7.2.8) . 
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Table 2-4 (Cont.) 
Special Function Keys 



Key 



Function 



Echoes to on the terminal and causes suppression of 
teleprinter output while continuing program execution. 
Teleprinter output is re-enabled when one of the 
following occurs: 



CTRL 



CTRL Q 



CTRL S 



CTRL U 



CTRL Z 



RUBOUT 



1. A second CTRL is typed, 

2. A return to the monitor occurs, or 

3. The running program issues a .RCTRLO 
directive (see Chapter 9). (RT-11 system 
programs reset CTRL to the echoing state 
each time a new command string is entered.) 

Does not echo. Resumes printing characters on the 
terminal from the point at which printing was 
previously stopped (via CTRL S) . CTRL Q has no special 
meaning if a SET TTY NOPAGE command has been used (see 
Section 2.7.2.8) . 

Does not echo. Temporarily suspends output to the 
terminal until a CTRL Q is typed. If GT ON is in 
effect, each subsequent CTRL A causes output to proceed 
until the screen has been refilled once. This feature 
allows users with high-speed terminals to fill the 
display screen, stop output with CTRL S, read the 
screen, and then continue with CTRL Q or CTRL A. 
(Typing CTRL C in this case also continues output.) 
Under the F/B Monitor, CTRL S has no special meaning if 
a SET TTY NOPAGE has been used. 

Deletes the current input line and echoes as tU 
followed by a carriage return at the terminal. (The 
current line is defined to be all characters back to, 
but not including, the most recent line feed, CTRL C or 
CTRL Z.) 

Echoes tZ on the terminal and terminates input when 
used with the terminal device handler (TT) . The CTRL Z 
itself does not appear in the input buffer. If TT is 
not being used, CTRL Z has no special meaning. 

Deletes the last character from the current line and 
echoes a backslash plus the character deleted. Each 
succeeding RUBOUT deletes and echoes another character. 
An enclosing backslash is printed when a key other than 
RUBOUT is typed. This erasure is done right to left up 
to the beginning of the current line. 



2.6.1 Foreground/Background Terminal I/O 

It is important to note that console input and output under F/B are 
independent functions; input can be typed to one job while output is 
printed by another. The user may be in the process of typing input to 
one job when the other job is ready to print on the terminal. In 
this case, the job which is ready to print interrupts the user 
and prints the message on the terminal; input control is not re- 
directed to this job, however, unless a CTRL B or CTRL F is explicitly 
typed. If input is typed to one job while the other has output 
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control, echo of the input is suppressed until the job accepting input 
gains output control; at this point all accumulated input is echoed. 

If the foreground job and background job are both ready to print 
output at the same time, the foreground job has priority. Output from 
the foreground job prints until a line feed is encountered, at which 
point output from the background job prints until a line feed is 
encountered, and so forth. 

When the foreground job terminates, control reverts automatically to 
the background job. 



2.6.2 Type- Ahe ad 

The monitor has a type-ahead feature which allows terminal input to b& 
entered while a program is executing. For example: 

. R PIP 

*DTl:TflPE=PR: 
DT1:/L 
+13-FEB-74 

TAPE 78 13-FEB-74 

486 FREE BLOCKS 

While the first command line is executing, the second line (DT1:/L) is 
entered by the user. This terminal input is stored in a buffer and 
used when the first operation has completed. 

If a single CTRL C is typed while in this mode, it is put into the 
buffer. The program currently executing exits when a terminal input 
request needs to be satisfied. A double CTRL C returns control to the 
monitor immediately. 

If type-ahead input exceeds 80 characters, the terminal bell rings and 
no characters are accepted until part of the type-ahead buffer is used 
by a program or characters are deleted. No input is lost. Type-ahead 
is particularly useful in specifying multiple command lines to system 
programs, as shown in the preceding example. If a job is terminated 
by typing two CTRL C*s, any unprocessed type-ahead is discarded. 

NOTE 

If type-ahead is used in conjunction 
with EDIT or BASIC, there is no terminal 
echo of the characters but they are 
stored in the buffer until a new command 
is needed. The characters are echoed 
only when actually used by the program. 



2.7 KEYBOARD COMMANDS 

Keyboard commands allow the tiser to communicate with the monitor. 
Keyboard commands can be abbreviated; optional characters in a 
command are delimited (in this section only) by braces. Keyboard 
commands require at least one space between the command and the first, 
argument. All command lines are terminated by a carriage return. 
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All commands, with the exception of those described in Section 2.7.5, 
may be used under either the Single-Job or F/B Monitor. The commands 
described in Section 2.7.5 apply only to the F/B Monitor. 



NOTE 

Any reference made to "the background 
job" applies as well to the Single-Job 
Monitor, since the background job in a 
F/B system is equivalent to the 
single- job environment in its normal 
state. 



2.7.1 Commands to Control Terminal I/O (GT ON and GT OFF) 



GT ON/GT OFF 



The GT ON and GT OFF commands are used to enable and disable the 
scroller (VT-11 display hardware) . GT ON causes the display screen to 
replace the console as the terminal output device. Switch options 
allow the user to control the number of lines to appear on the screen 
and to position the first line vertically. Output appears on the 
display in the same format as it would on the console (i.e., output, 
text, and commands are displayed in the order in which they occur) . 
GT ON is not permitted in an 8K configuration. 



The form of the GT ON command is: 
GT ON|/L:n||/T:nl 



where : 



/L:n represents an optional switch setting indicating the 
number of lines of text to display; the suggested 
range is : 



12" screen 

(GT40, DEClab) 

17" screen 
(GT44) 



l<=n<=37 octal (31 decimal) 
K=n<=50 octal (40 decimal) 



/T:n represents an optional switch setting indicating the 
top position of the scroll display; the suggested 
range is : 



12" screen 

(GT40, DEClab) 



K=n<=1350 octal (744 decimal) 
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17" screen K-n<=1750 octal (1000 
(GT44) decimal) 

If no switches are specified, a test for the screen size is performed 
and default values are automatically assigned as follows: 

12" screen /L:37 (31 decimal) 
(GT40, DEClab) /T:1350 (744 decimal) 

17" screen /L:50 (40 decimal) 
(GT44) /T:1750 (1000 decimal) 

Line length is always set to 72 for 12" screen and 80 for 17" screen. 
Once the display has been activated with the GT ON command, CTRL A, 
CTRL S, CTRL E and CTRL Q can be used to control scrolling behavior. 
These commands are described in Section 2.6. 

NOTE 

ODT is one exception to the use of GT 
ON. This system program has its own 
terminal handler and cannot make use of 
the display; output will appear only on 
the console terminal whenever ODT is 
running. 

The GT OFF command clears the display and resumes output on the 
teleprinter. The command format is: 

GT OFF 

If GT ON and GT OFF are used when no display hardware exists or when a 
foreground job is active, the ?ILL CMD? message is printed. 



2.7.2 Commands to Allocate System Resources 




2.7.2.1 DATE Command - The DATE command enters the indicated date to 
the system. This date is then assigned to newly created files, new 
device directory entries (which may be listed with PIP) , and listing 
output until a new DATE command is issued. 

The form of the command is: 
DAT<e{- <dd-mmm-yy> 

where dd-mmm-yy is the day, month and year to be entered. dd is a 
decimal number in the range 1-31; mram is the first three characters of 
the name of the month, and yy is a decimal number in the range 73-99. 
If no argument is given, the current date is printed. 
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Examples : 



DATE 21-FEB-74 



. DAT 
21-FEB-74 



Enter the date 21-FEB-74 as the current 
system date. 

Print the current date. 



If the date is entered in an incorrect format, the ?DAT? error 
message is printed. 




2.7.2.2 TIME Command - The TIME command allows the user to find out 
the current time of day kept by RT-11 or to enter a new time of day. 
If no KWll-L clock is present on the system, the ?N0 CLOCK? error 
message is generated. If the time is entered in an incorrect format, 
the ?TIM? message is printed. 

The form of the command is: 



TIM 



Ml 



hh:mm:ss> 



where hh:mm:ss represents the hour, minute, and second. Time is 
represented as hours, minutes, and seconds past midnight in 24-hour 
format (e.g., 1:25:00 P.M. is entered as 13:25:00). If any of the 
arguments are omitted, is assumed. If no argument is given, the 
current time of day is output. 



Examples : 



TIM 8:15:2: 



.TIM 

08 : 25 : 27 

. TIME 18:5 



Sets the time of day to 8 hours, 15 
minutes and 23 seconds. 

Approximately 10 minutes later, the 
TIME command outputs this time. 

Sets the time of day to 18:05:00. 



Under the F/B Monitor, after the time reaches 24:00, the time and date 
will be reset when the user next issues a TIME command (or .GTIM pro- 
grammed request) . Time and date are not reset under the Single-Job 
Monitor. Month and year are not updated under either monitor. 

The clock rate is initially set to 60-cycle. Consult the RT-11 System 
C?eneration Manual if conversion to a 50-cycle rate is necessary. 
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INITIALIZE 



2.7.2.3 INITIALIZE Command - The INITIALIZE command is used to reset 
several background system tables and do a general "clean-up" of the 

background area; it has no effect on the foreground job. In 
particular, this command makes non-resident those handlers which were 
not loaded (via LOAD), purges the background's I/O channels, disables 
CTRL 0, performs a hard reset, clears locations 4 0-53, resets the KMON 
stack pointer, and under the F/B monitor performs an .UNLOCK. 

Under the Single- Job Monitor a RESET instruction is done (see Chapter 
9) . Under the F/B Monitor, I/O is stopped by entering each busy de- 
vice handler at a special abort entry point. 

The form of the command is : 

initialize}- 

The INITIALIZE command can be used prior to running a user program, or 
when the accumulated results of previously issued GET commands (see 
Section 2.7.3.1) are to be discarded. 



Example : 



IN Initializes system background job 

, K r R U u 



ASSIGN 



2.7.2.4 ASSIGN Command - The ASSIGN command assigns a user-defined 
(logical) name as an alternate name for a physical device. This is 
especially useful when a program refers to a device which is not 
available on a certain system. Using the ASSIGN command, I/O can be 
redirected to a device which is available. Only one logical name can 
be assigned per ASSIGN command, but several ASSIGN commands (14 
maximum) can be used to assign different names to the same device. 
This command is also used to assign FORTRAN logical units to device 
names. 



January 1976 2-13 



System Communication 

The form of the command is: 

ASSJiGnI •j<jdevj-:udevj> 



where : 

dev is any standard RT-11 (physical) device name 
(refer to Table 2-2) with the exception of DK and 
SY. 

udev is a 1-3 character alphanumeric (logical) name to 
be used in a program to represent dev (if more 

than three characters are given, only the tirst 
three are actually used) . DK and SY may be used 
as loqical device names. 

: is a delimiter character (can be a colon, equal 
sign, and, if separating physical and logical 
devices, space). 

The placement of the delimiter is very important in the ASSIGN 
command; it must be placed exactly as shown in the following 
examples : 

ASSIGN DTI INP Physical device DTI is assigned the 

logical device name INP. Whenever a 

reference to INP: is encountered, 
device DTI: is used. 

ASSIGN DT3:DK Physical device name DT3 is assigned the 

default device name DK. Whenever DK is 

referenced or defaulted to, DT3 is used. 
(Note that the initial assignment of DK 
is thus changed.) 



. ASSIGN LP = 9 FORTRAN logical unit 9 becomes the 

physical device name LP. All references 
to unit 9 use the line printer for 
output. 

Assignment of logical names to logical names is not allowed. 

If only a logical device name is indicated in the command line, that 
particular assignment (only) is removed. Thus: 

.ASSIGN :3 Deassigns the logical name 9 from its 

physical device (LP, in the case above) . 

. ASSIGN =DK Removes assignment of logical name DK 

from its physical device (DT3, in the 
case above) . 

If neither a physical device name nor a logical device name is 
indicated, all assignments to all devices are removed. 

. ASSIGN All previous logical device assignments 

are removed. 
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2.7.2.5 CLOSE 
output files 
tentative open 
deleted. The 
typed to abort 
had open prior 



Command - The CLOSE command causes all currently open 
in the background job to become permanent files. If a 
file is not made permanent, it will eventually be 
CLOSE command is most often used after CTRL C has been 
a background job and to preserve any new files that job 
to the CTRL C; it has no effect on a foreground job. 



The form of the command is: 

cloIse\ 
The CLOSE command makes temporary directory entries permanent. 



Example: 



R EDIT 
*EWTEXT** 
IfiBCD** 



The Editor has a temporary 
file open (TEXT) , which is 
preserved by .CLOSE. 



i: 



CLOSE 




2.7.2.6 LOAD Command - The LOAD command is used to make a device 
handler resident for use with background and foreground jobs. 
Execution is faster when a handler is resident, although memory area 
for the handler must be allocated. Any device handler to be used by a 
foreground job must be loaded before it can be used. 

The form of the command is: 



LOA |dI dev / , dev=B > j, dev=F , . . . > 



where: 



dev 

ss 

B 

F 



represents any legal RT-11 device name, 
represents a delimiter, denoting device ownership, 
represents the background job. 
represents the foreground job. 



The dev=F (and dev=B) construction is valid only under the 
Foreground/Background system. When used under the Single- Job Monitor, 
the ?ILL EV? error message occurs. 
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A device may be owned exclusively by either the foreground or 
background job. This may be used, for example, to prevent the I/O of 
two different jobs from being intermixed on the same non-file 
structured device. For example: 

♦ LOAD PI :: '--B!'PRi'I...P : =-F The paper tape punch belongs to the 

background job while the paper tape 
reader is available for use by 
either the background or foreground 
job; the line printer is owned by 
the foreground job. All three 
handlers are made resident in 
memory . 

Different units of the same random-access device controller may be owned 
by different jobs. Thus, for example, DTI may belong to the background 
while DT5 may belong to the foreground job. If no ownership is 
indicated, the device is available for public use. 

To change ownership of a device, another LOAD command may be used; it 
is not necessary to first UNLOAD the device. For example, if RKl has 
been assigned to the foreground job as in the example above, the 
command : 

. L.OA RKJ.==B 
reassigns it to the background job. 

The system unit of the system device cannot be assigned ownership, and 
attempts to do so will be ignored. Other units of the same type as 
the system device, however, can be assigned ownership. 

LOAD is valid for use with user-assigned names. For example: 

.ASSIGN RK2SXY 
,LOA XY:=-F 



If the Single-Job, DECtape-based Monitor is being used, loading the 
necessary device handlers into memory can significantly improve the 
throughput of the system, since no handlers need to be loaded 
dynamically (in other words, they need not be loaded, as required, 
from the DEC tape) . 



UNLOAD 



2.7.2.7 UNLOAD Command - The UNLOAD command is used to make handlers 
that were previously LOADed non-resident, freeing the memory they were 
using. 

2-21 January 1976 



System Communication 

The form of the command is : 

UNl|0AD> dev j,dev,. . .1 

where : 

dev represents any legal RT-11 device name. 

UNLOAD clears ownership for all units of an indicated device type. 
For example, typing: 

UNL RK2 

clears all units of RK. (A request to unload the system device 
handler clears ownership for any assigned units for that device, but 
the handler remains resident.) 

Any memory freed is returned to a free memory list and eventually 
reclaimed for the background job after the UNLOAD command is given. 
UNLOAD is not permitted if the foreground job is running. Such an 
action might cause a handler which is needed by the foreground job to 
become non-resident. 

Example : 

.UNLOAD LP.PP The lineprinter and paper tape 

punch handlers are released and the 
area which they used is freed. 

A special function of this command is to remove a terminated 
foreground job and reclaim memory, since the space occupied by the 
foreground job is not automatically returned to the free memory list 
when it finishes. In this instance, the device name FG is used to 
specify the foreground job. For example: 

. UNL FG 

FG can be mixed with other device names. 

However, if, for example, DT2 has been assigned the name FG and loaded 
into memory as follows : 

.ASSIGN Di"2;F6 

.LOAD FG 

the command: 

, UNLOAD l-G 

causes the foreground job, not DT2, to be unloaded. To unload DT2, 
this command must be typed: 

. UNLOAD DT2 
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2,7.2.8 SET Command - The SET command is used to change device 
handler characteristics and certain system configuration parameters. 



The form of the command is : 

SET de v : i Nol opt ion=value 
where : 



/,<JNO>option=value, . . .( 



dev: 



represents any legal RT-11 physical device 

name (and in addition, TTY and USR) . 



|noI option is the feature or characteristic to 



=value 



altered. 

is a decimal number required in some cases. 



be 



A space may be used in place of or in addition to the colon, equal 
sign, or comma. Note that the device indicated (with the exception of 

TTY and USR) must be a physical device name and is not affected by logical 
device name assignments which may be active. The name of the 
characteristic or feature to be altered must be legal for the 
indicated device (see Table 2-5) and may not be abbreviated. 

The SET command locates the file SY:dev.SYS and permanently modifies 
it. No modification is done if the command entered is not completely 
valid. If a handler has already been loaded when a SET command is 
issued for it, the modifications will not take effect until the 
handler is unloaded and a fresh copy called in from the system device. 

Table 2-5 lists the system characteristics and parameters which may be 

altered (those modes designated as "normal" are the modes as set in the 
distribution copies of the drivers) : 

Table 2-5 
SET Command Options 



Device 



LP 



LP 



LP 



Option 



CR 



NOCR 



CTRL 



Alteration 



Allows carriage returns to be sent to the 

printer. The CR option should be set for any 
FORTRAN program using formatted I/O, to allow 
the overstriking capability for any line print- 
er, and when using the LS11 or LP05 line print- 
ers (since the last line in the buffer may 
otherwise be lost). This is the normal mode. 

Inhibits sending carriage returns to the line 

printer. The line printer controller causes a 
line feed to perform the functions of a carriage 
return, so using this option produces a signi- 
ficant increase in printing speed on LP11 print- 
ers. 

Causes all characters, including nonprinting con- 
trol characters, to be passed to the line printer. 
This mode may be used for LS11 line printers. 
(Other line printers will print space for control 
characters. 1 
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Table 2-5 (Cont.) 
SET Command Options 



Device 



LP 
LP 

LP 
LP 



Option 



LP 



LP 



LP 



LP 



CR 



CR 



CR 



CR 



CR 



NOCTRL 
FORMO 

NOFORMO 
HANG 



NOHANG 



LC 



NOLC 



WIDTH=n 



CODEsn 



CRLF 



NOCRLF 



HANG 



NOHANG 



Alteration 



Ignores nonprinting control characters. This is 
the normal mode. 

Causes a form feed to be issued before a 
request to print block zero. This is the 
normal mode. 

Turns off FORMO mode. 

Causes the handler to wait for user 

correction if the line printer is not ready 

or becomes not ready during printing. This 
is the normal mode. 

New users should note that when expecting 
output from the line printer and it appears 
as though the system is not responding or is 
in an idle state, the line printer should be 
checked to see if it is on and ready to 
print. 

Generates an immediate error if the line 
printer is not ready. 

Allows lower case characters to be sent to 
the printer. This option should be used if 
the printer has a lower case character set. 

Causes lower case characters to be translated 
to upper case before printing. This is the 
normal mode. 

Sets the line printer width to n, where n is 
a number between 30 and 255. Any characters 
printed past column n are ignored. The NO 
modifier is not permitted. 

Modifies the card reader handler to use 
either the DEC 026 or the DEC 029 card codes 
(refer to Appendix H) . n must be either 26 or 
29. The NO modifier is not permitted. 

Causes a carriage return/line feed to be 
appended to each card image. This is the 
normal mode. 

Transfers each card image without appending a 
carriage return/line feed. 

Causes the handler to wait for user 
correction if the reader is not ready at the 
start of a transfer. This is the normal 
mode. 

Generates an immediate error if the device is 
not ready at the start of a transfer. Note 
that the handler will wait regardless of how 
the option is set if the reader becomes "not 
ready" during a transfer (i.e., the input 
hopper is empty, but an end-of-file card has 
not yet been read) . 
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•rabie 2-5 (Cont.) 
SET Command Options 



Device 



Option 



Alteration 



CR 



IMAGE 



Causes each card column to be stored as a 
12-bit binary number, one column per word. 
The CODE option has no effect in IMAGE mode. 
The format of the 12-bit binary number is: 



PDP-11 WORD 
15 14 13 



12 11 



UNUSED (ALWAYS 0) 



ZONE ZONE ZONE 



ZONE 

1 



ZONE ZONE ZONE ZONE ZONE ZONE ZONE ZONE 
23456789 



CR 



NOIMAGE 



CR 



TRIM 



CR 
CT 



NOTRIM 
RAW 



CT 



NORAW 



This format allows binary card images to be 
read and is especially useful if a special 
encoding of punch combinations is to be used. 
Mark-sense cards may be read in IMAGE mode. 

Allows the normal translation (as specified 
by the CODE option) to take place; data is 
packed one column per byte. Invalid punch 
combinations are translated into the error 
character, ASCII "\" (backslash), which is 
octal code 134. This is the normal mode. 

Causes trailing blanks to be removed from 

each card read. It is not recommended that 

TRIM and NOCRLF be used together since card 

boundaries will be difficult to find. This 
is the normal mode. 

Transfers a full 80 characters per card. 

Causes the cassette handler to perform a 
read-after-write check for every record 
written, and retry if an output error 
occurred. If three retries fail, an output 
error is detected. 

Causes the cassette handler to write every 
record directly without reading it back for 
verification. This significantly increases 
transfer rates at the risk of increased error 
rates. Normal mode is NORAW. 



The following options, with the exception of HOLD/NOHOLD and 
C0PY/N0C0PY, are available in the Foreground/Background System only; 
HOLD/NOHOLD and COPY/NOCOPY are available in both systems. These 
options are not permanent, and must be reissued whenever the monitor 
is re-bootstrapped. They can be made permanent by modifying the moni- 
tor as described in Chapter 2 of the RT-11 Software Support Manual . 
(Note that the device specification is TTY, not TT, because the hand- 
ler itself is not changed . ) 



TTY 



TTY 



COPY 



NOCOPY 



Enables use of the auto-print mode of the 
VT50 copier option, if present. The com- 
mand is a no-op for any terminal other than 
the VT50, but a "]" character may be printed 
on the terminal. Consult the VT50 Video Ter- 
minal Programmer's Manual for more infor- 
mation^ 

Disables use of the auto-print mode of the 
VT50 copier option, if present. The command 
is a no-op for any terminal other than the 
VT5 , but a "* " character may be printed on 
the terminal. This is the normal mode. 
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Table 2-5 (Cont.) 
SET Command Options 



Device 



option 



Alteration 



TTY 



CRLF 



TTY 



TTY 



NOCRLF 



FB 



TTY 



NOFB 



TTY 



TTY 



TTY 



TTY 



TTY 



FORM 



NOFORM 



HOLD 



NOHOLD 



PAGE 



Causes the monitor to issue a carriage 
return/line feed on the console terminal 
whenever it attempts to type past the right 
margin (as set by the WIDTH option) . This is 
the normal mode. 



Causes no special action to be taken 
right margin. 



at the 



Causes the monitor to treat CTRL B and CTRL F 
characters as background and foreground 
program control characters and does not 
transmit them to the user program. This is 
the normal mode. 



Causes CTRL B and CTRL F to have 
meaning. 

NOTE 



no special 



SET TTY NOFB is issued to KMON, 
(which runs as a background job) 
and disables all communication with 
the foreground job. To enable 
communication with the foreground 
job, issue the command SET TTY FB. 

Indicates that the console terminal 
capable of executing hardware form feeds. 



is 



Causes the monitor to simulate form feeds by 
typing eight line feeds. This is the normal 
mode. 

Enables use of the hold screen mode of op- 
eration for the VT50 terminal. The command 
is a no-op for any terminal other than the 
VT50, but a "[" character may be printed on 
on the terminal. The command is valid for 
F/B and Single-Job Monitors. Consult the 
VT50 Video Terminal Programmer's Manual for 
more information. 

Disables use of the hold screen mode of op- 
eration for the VT50 terminal. The command 
is a no-op for any terminal other than the 
VT50, but a H \" character may be printed on 
the terminal. This is the normal mode. 

Causes the monitor to treat CTRL S and CTRL Q 
characters as terminal output hold and unhold 
flags, and does not transmit them to the user 
program. This is the normal mode. 



(continued on next page) 
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Table 2-5 (Cont.) 

SET Command Options 


Device 


Option 


Alteration 


TTY 


NOPAGE 


Causes CTRL S and CTRL Q to have no special 
meaning. 


TTY 


SCOPE 


Causes the monitor to echo RUBOUTs as 
backspace-space- backspace. This mode should 
be used when the console is a VT05/VT50 or 
when GT ON is in effect. 


TTY 


NOSCOPE 


Causes the monitor to echo RUBOUTs as 
backslash followed by the character deleted. 
This is the normal mode. 


TTY 


TAB 


Indicates that the console terminal is 
capable of executing hardware tabs. 


TTY 


NOTAB 


Causes the monitor to simulate tab stops 
every eight positions. The normal mode is 
NOTAB. VT05/VT50 terminals generally have 
hardware tabs. 


TTY 


WIDTH =n 


Sets the width of the console terminal to n 
positions, for the use of the CRLF option, n 
must be in the range 30-255 (decimal) . The 
width is initially set to 72. 



The following variant of the SET command is used to prevent the 
background job from ever placing the USR in a swapping state (note 
that USR replaces a device specification in the command line) : 



SET USR 



{no} 



SWAP 



This is useful when running on a DECtape based system, or when running 
a foreground job which requires the USR but has no memory allocated 
into which to read it. When the monitor is bootstrapped, it is in the 
SWAP condition, i.e., the background may place the USR in a swapping 
state via a SETTOP. 

The Single-Job Monitor behaves as though the following options are 
set: NOTAB, NOFORM, PAGE, NOCRLF, NOSCOPE, NOHOLD. 
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2.7.3 Commands to Manipulate Memory Images 




2.7.3.1 GET Command - The GET command (valid for use with a 
background job only) loads the specified memory image file (not ASCII 
I or object) into memory from the indicated device. 



The form of the GET command is : 
GE<T> devsfilnam.ext 
where : 



- represents any legal RT-11 device name. If a 

device is not specified, DK: is assumed. Note 
that devices MT and CT are not block-replaceable 
devices and therefore cannot be used in a GET 
command . 

filnam.ext represents a valid RT-11 filename and extension., 
If an extension is not specified, the extension 
.SAV is assumed. 

The GET command is typically used to load a program into memory for 
modification and/or debugging. The GET command can also be used in 
conjunction with the Base, Examine, Deposit, and START commands to 
test patches, and can be used with SAVE to make patches permanent,, 
Multiple GETs can be used to combine programs. Thus: 

Loads ODT into memory 

. GET ODT. SflV 

Loads PROG. SAV into 
. GET PROG memory with ODT 

. START (ODTs starting address) Starts execution with ODT 

(see Chapter 8) . 

The GET command cannot be used to load overlay segments of programs; 
it may only be used to load the root segment (that part which will not 
be overlaid? refer to Chapter 6, Linker). 

Multiple GETs can be used to build a memory image of several programs. 
If identical locations are required by any of the programs, the later 
programs overlay the previous ones. 



Examples: 



GET DT3.FI LEI. SflV Loads the file FILE 1. SAV into memory 

from DECtape unit 3. 

GET NRHE1 Loads the file NAME1.SAV from device DK. 
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2.7.3.2 Base Command - The B command sets a relocation base. This 
relocation base is added to the address specified in subsequent 
Examine or Deposit commands to obtain the address of the location to 
be referenced. This command is useful when referencing linked modules 
with the Examine and Deposit commands. The base address can be set to 
the address where the module of interest is loaded. The form of the 
command is: 



B i location}. 



where : 



location represents an octal address used as a base address for 
subsequent Examine and Deposit commands. 

NOTE 

A space must follow the B command 
even if an address is not specified 
(the B< space > command is equivalent 
to B 0) . 

Any non-octal digit terminates an address. If location 
is odd, it is rounded down by one to an even address. 

The base is cleared whenever user program execution is initiated. 

Examples : 

. BA Sets base to ( A represents space). 

. B 26@ Sets base to 200. 

. B 201 Sets base to 200. 
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EXAMINE 



2.7.3.3 Examine Command - The E command prints the contents of the 
specified location (s) in octal on the console terminal. The form of 
the Examine command is: 



E location ml -location n[ 



where: 



location represents an octal address which is added to the 
relocation base value (the value set by the B Command) 
to get the actual address examined. Any non-octal 
digit terminates an address . An odd address is 
truncated to become an even address. 

If more than one location is specified (location m- location n) , the 
contents of location m through location n inclusive are printed. The 
second location specified (location n) must not be less than the first 
location specified, otherwise an error message is printed. If no 
location is specified, the contents of location are printed. 
Examination of locations outside the background area is illegal. 



Examples : 



. E 1000 

127461 



Prints contents of location 1000 (added 
to the base value if other than 0) . 



. E 1081-1012 

127401 067624 127400 000000 000000 000000 

Prints the contents of locations 1000 
(plus the base value if other than 0) 
through 1013. 



DEPOSIT 



2.7.3.4 Deposit Command - The Deposit command deposits the specified 
value (s) starting at the location given. 

The form of the command is j 

D location=valuel| value2 , . . . valuen > 



January 197 6 



2-30 



System Communication 

where s 

location represents an octal address which is added to the 
relocation base value to get the actual address where 
the values are deposited. Any non-octal digit is 
accepted as a terminator of an address. 

value represents the new contents of the location. is 
assumed if a value is not indicated. 

If multiple values are specified (valuel, . . . ,valuen) , they are 
deposited beginning at the location specified. The DEPOSIT command 
accepts word or byte addresses but executes the command as though a 
word address was specified. An odd address is truncated by one to an 
even address. All values are stored as word quantities. 

Any character that is not an octal digit may be used to separate the 
locations and values in a DEPOSIT command. However, two (or more) 
non-octal separators cause O's to be deposited at the location 
specified (and those following) . For example: 

.D 56,,, Deposits O's in locations 56, 60, and 62. 

The user should be aware of situations like the above, which causes 
system failure since the terminal vector (location 60) is zeroed. 

An error results when the address specified references a location 
outside the background job's area. 



Examples ; 



D 1000=3705 Deposits 3705 into location 1000 

B 1608 Sets relocation base to 1000 

D 1500=2502 Puts 2503 into location 2500 

6 Resets base to 




2.7.3.5 SAVE Command - The SAVE command writes specified user memory 
areas to a named file and device in save image format. Memory is 

written from location to the highest memory address specified by the 
parameter list or to the program high limit (location 50 in the system 
communication area) . 

The SAVE command does not write the overlay segments of programs; it 
saves only the root segment (refer to Chapter 6, Linker). 

The form of the command is : 



SAWEV dev:filnam.ext .{parameters!* 



where : 



dev: represents one of the standard RT-11 block-replaceable 
device names. If no device is specified, DK is 
assumed. 
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file.ext represents the name to be assigned to the file being 
saved. If the file name is omitted, an error message 
is output. If no extension is specified, the extension 
•SAV is used. 

parameters represent memory locations to be saved. RT-11 transfers 
memory in 256-word blocks beginning on boundaries that 
are multiples of 256 (decimal) . If the locations speci- 
fied make a block of less than 256 words, enough addi- 
tional locations are transferred to make a 256-word block. 

Parameters can be specified in the following format: 

areal , area2-arean 

where : 

areal represent an octal number (or numbers 

area2-arean separated by dashes) . If more than one number 

is specified, the second number must be 

greater than the first. 

The start address and the Job Status Word are given the default value 
and the stack is set to 1000. If the user wants to change these or 
any of the following addresses, he must first use the DEPOSIT command 
to alter them and then SAVE the correct areas: 

Area Location 



Start address 


40 


Stack 


42 


JSW 


44 


USR address 


46 


High address 


50 


Fill characters 


56 



If the values of the addresses are changed, it is the user's 
responsibility to reset them to their default values. See Chapter 9 
for more information concerning these addresses. 



Examples : 



SAVE FILE1 16000-11000,14600-14100 

Saves locations 10000(8) through 
11777(8) (11000 starts the first word of 
a new block, therefore the whole block, 
up to 12000, is stored) and 14000(8) 
through 14777(8) on DK with the name 
FILE 1. SAV. 

. SAVE DTI: NAM. NEW 10000 

Saves locations 10000 through 10777 on 
DTI: with the name NAM. NEW. 

D 44:28000 

SflV SV:PRUM 1000-577? 

Sets the reenter bit in the JSW and 
saves locations 1000 through 5777. 
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2.7.4 Commands to Start a Program 




2.7.4.1 RUN Command - The RUN command (valid for use with a 
background job only) loads the specified memory image file into memory 
and starts execution at the start address specified in location 40. 
Under the F/B system, 10 words of user stack area are required to 
start a user program, and the stack address (location 42) must be 
initialized to some part of memory where these 10 words will not 
modify it. 

The form of the command is : 

Ru/nI dev:filnam.ext 

where : 

devt is any standard device name specifying a 
block- replaceable device. If dev: is not specified, 
the device is assumed to be DK. Note that devices MT 
and CT are not block-replaceable devices and 
therefore cannot be used in a RUN command. 

filnam.ext is the file to be executed. If an extension is not 
specified, the extension .SAV is assumed. 

The RUN command is equivalent to a GET command followed by a START 
command (with no address specified) . 

NOTE 

If a file containing overlays is to be RUN from 
a device other than the system device, the handler 
for that device must be loaded (see Section 2.7.2.6) 
before the RUN command is issued. 

Examples % 

.RUN DT1:SRCH. SflV Loads and executes the file SRCH.SAV 

from DTI. 

.RUN PROG Loads PROG. SAV from DK and executes the 

program. 

.GET PR0G1 Loads PROG1.SAV from device DK without 

executing it. Then combines PROGl and 

.RUN PR0G2 PROG2.SAV in memory and begins execution 

at the starting address for PROG2. 
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2.7.4.2 R Command - This command (valid for use with the background 
job only) is similar to the RUN command except that the file specified 
must be on the system device (SY:). 

The form of the command is: 

R filnam.ext 



No device may be specified, 
extension .SAV is assumed. 



If an extension is not given, the 



Examples : 



. R XV 2. SflV Loads and executes XYZ.SAV from SY. 
. R SRC Loads and executes SRC. SAV from SY. 



START 



2.7.4.3 START Command - The START command begins execution of the 
program currently in memory (i.e., loaded via the GET command) at the 
specified address. START does not clear or reset memory areas. 

The form of the command is: 

I ST-ZartI i address > 

where : 

address is an octal number representing any 16-bit 
address. If the address is omitted, or if is 
given, the starting address in location 40 will be 
used. 

If the address given does not exist or is not an even address, a trap 
to location 4 occurs. In this case a monitor error message appears. 
If no address is given, the program's start address from location 40 
is used. 



July 1975 
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.GET FILE.l Loads PILE.l into memory and starts execution 
.START 1000 at location 1000. 



.GET FILE: A Loads FILEA.SAV, then combines FILEA.SAV with 
FILEB.SAV and starts execution at FILEB's 
( get files start address. 



REENTER 



2.7.4.4 REENTER Command - The REENTER command starts the program at 
its reentry address (the start address minus two) . REENTER does not 
clear or reset any memory areas and is generally used to avoid 
reloading the same program for repetitive execution. It can be used 
to return to a program whose execution was stopped with a CTRL C. 

The form of the command is: 

re-enter} 

If the reenter bit (bit 13) in the Job Status Word (location 44) is 
not set, the REENTER command is illegal. 

For most system programs, the REENTER command restarts the program at 
the command level. 

If desired, the reentry point in a user program can branch to a 
routine which initializes the tables and stack, fetches device 
handlers etc. , and then continue normal operation. 

Example : 

. R PIP CTRL C interrupts the PIP 

+ ,'F directory listing and transfers 

MONITR. SVS control to the monitor level, 

[directory prints] REENTER returns control to PIP. 

• ( tc typed) 

• 

REENTER 

2.7.5 Commands Used Only in a Foreground/Background Environment 

It is important to note that in order to control execution of a 
foreground job, the commands in this section must be typed to KMON, 
which is running as the background job. Thus, for example, to SUSPEND 
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the foreground job, the user must be sure he is directing input to 
KMON as follows : 

F> Foreground job is running. Control 

(tB typed) is redirected to the background job 

B> and PIP is called (the foreground 

R PIP is still active). CTRL C stops PIP 

*"C and starts KMON. The foreground 

. SUSPEND job is suspended. (See Section 

2.7.5.2.) 




2.7.5.1 FRUN Command - The FRUN command is used to initiate 
foreground jobs. FRUN will only run relocatable files produced with 
the Linker /R switch (using the Linker supplied with RT-11, Version 
2). Any handlers used by a foreground job must be in memory. 

The form of the command is: 



FRU |n| dev : f ile . ext j/N : nl j/S : nl j/P j- 



where: 



dev: represents a block replaceable RT-11 device. If 

dev: is not specified, DK: is assumed. 

file. ext represents the job to be executed. The default 
extension for a foreground job is .REL. 

/N:n or /Nln represents an optional switch used to allocate n 
words (not bytes) over and above the actual 
program size. (If running a FORTRAN program, a 
special formula is used to determine n. Refer to 
Appendix G for this information.) 

/S:n or /Sin represents an optional switch used to allocate n 
words (not bytes) for stack space. Normally, 
stack space is set by default to 128 words and is 
placed in memory below the program. To change the 
stack size, use /S:n; the stack is still placed in 
memory under the program. To relocate the stack 
area, use an .ASECT (see Chapter 5) to define the 
start of the user stack in location 42. This 
overrides the /S switch. 

/P represents an optional switch (at the end of the 

FRUN command) for debugging purposes. When the 
carriage return is typed, FRUN prints the load 
address of the program, but does not start the 
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program. The foreground job must be explicitly 
started with the RSUME command (see Section 
2.7.5.3). For example: 

. FRUN DRTfi/P 
LOADED RT 125444 

If ODT is used with the foreground job, this 
feature provides the means for determining where 
the job actually was loaded. 

The program is started when the RSUME command is 
given, allowing the programmer to examine or 
modify the program before starting it. 

If another foreground job is active when the FRUN command is given, an 
error message is printed. If a terminated foreground job is occupying 
memory, that region is first reclaimed. Then if the file indicated is 
found and will fit in memory, the job is installed and started 
immediately. FRUN destroys the background job's memory image. 

Examples : 

.FRUN Fl Runs program Fl.REL stored on device DK. 

. FRU DT1:F£ Runs F2.REL which is on DTI. 



SUSPEND 



2.7.5.2 SUSPEND Command - The SUSPEND command is used to stop 
execution of the foreground job. 

The form of the command is: 

sus|pend| 

No arguments are required. Foreground I/O transfers in progress will 
be allowed to complete; however, no new I/O requests will be issued 
and no completion routines will be entered (see Chapter 9 for a 
discussion of completion routines) . Execution of the job can be 
resumed only from the keyboard. 



Example : 



SUSPEND Suspends execution of the foreground job currently 
running. 
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2.7.5.3 RSUME Command - The RSUME command is used to resume execution 
of the foreground job where it was suspended. Any completion routines 
which were scheduled while the foreground was suspended are entered at 
this time. 

The form of the command is: 

rsu|me| 

No arguments are required. 

Example : 

. RSU Resumes execution of the foreground job currently 
suspended. 



2.8 MONITOR ERROR MESSAGES 

The following error messages indicate fatal conditions that can occur 
during system boot: 



Message 

7B-I/0 ERROR 
?B-NO BOOT ON VOLUME 
7B-N0 MONITR.SYS 
7B-N0T ENOUGH CORE 



Meaning 

An I/O error occurred during system boot. 

No bootstrap has been written on volume. 

No monitor exists on volume being booted. 

There is not enough memory for the system 
being booted (e.g., attempting to boot 
F/B into 8K) . 



The following error messages are output by the Keyboard Monitor. 



Message 

f/WJDR? 
?DAT? 



?ER RD OVLY? 



F? 

?F ACTIVE? 

?FIL NOT FND? 

?FILE? 

January 197 6 



Meaning 

Address out of range in E or D command. 

The DATE command argument was illegal, 
or no argument was given and the date 
has not yet been set. 

An I/O error occurred while reading a 
KMON overlay to process the current 
command. This is a serious error, 
indicating that the system file 
MONITR.SYS is unreadable. 

A CTRL F was typed under the F/B monitor 
and no foreground job exists. 

Neither FRUN nor UNLOAD may be used when 
a foreground job already exists and is 
active . 

File specified in R, RUN, GET, or FRUN 
command not found. 

No file named where one is expected. 
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Meaning 



?ILL CMD? 



?ILL DEV? 



Illegal Keyboard Monitor command 
command line too long. 



or 



?N0 CLOCK? 
?N0 FG? 

?OVR COR? 

7PARAMS? 

?REL FIL I/O ER? 

?SV FIL I/O ER? 



Illegal or nonexistent device, or an 
attempt was made to make a device 
handler resident for use with a 
foreground job (dev=F) when the 
Single-Job Monitor was running. 

No KW11L clock is available for the TIME 
command . 

A SUSPEND, RSUME, or UNLOAD FG command 
was given, but no foreground job was in 
memory . 

Attempt to GET or RUN a file that is too 
big. 

Bad parameters were typed to the SAVE 
command. 

Either the program requested is not a 
REL file or a hardware error was 
encountered trying to read or write the 

file. 

I/O error on .SAV file in SAVE (output) 

or R, RUN, or GET (input) command. Pos- 
sible errors include end-of-file, hard 
error, and channel not open. 



?SY I/O ER? 
?TIM? 



I/O error on system device (usually 
reading or writing swap area) . | 

The TIME command argument was illegal. 



The following messages are output by the RT-11 Resident Monitor when 
an unrecoverable error has occurred. Control passes to the Keyboard 
Monitor. The program in which the error occurred cannot be restarted 
with the RE command. To execute the program again, use the R or RUN 
command . 



The format for fatal monitor error messages is: 
?M-text PC 



where PC is the address+2 of 
location where the error occurred. 



the 



Note that ?M errors can be inhibited in certain cases by the use of 
the .SERR macro; see Chapter 9 for details. 



Message 
?M-BAD FETCH 



Meaning 

Either an error occurred while reading 
in a device handler from SY, or the 
address at which the handler was to be 
loaded was illegal. 



2-39 



January 1976 



System Communication 
7M-DIR 10 ERR 

7M-DIR OVFLO 

7M-DIR UNSAFE 



?M-FP TRAP 



An error occurred doing 
directory of a device (e.g. , 
write- locked device) . 



I/O in the 
.ENTER on a 



No more directory segments were 
available for expansion (occurs during 
file creation (.ENTER)). 

In F/B only, this message may appear in 
addition to any of the other diagnostics 
listed in this section. It indicates 
that the error occurred while the USR 
was updating a device directory. One or 
more files on that device may be lost. 

A floating-point exception trap 
occurred, and the user program had no 
.SFPA exception routine active (see 
Chapter 9) . 



7M-ILL ADDR 



Under the F/B Monitor, an address 
specified in a monitor call was odd or 
was not within the job's limits. 



7M-ILL CHAN 



7M-ILL EMT 



7M-ILL USR 



7M-N0 DEV 



7M-0VLY ERR 



7M-SWAP ERR 



A channel number was specified which was 
too large. 

An EMT was executed which did not exist; 
i.e., the function code was out of 
bounds . 

The USR was called from a completion 
routine. This error does not have a 
soft return (i.e., .SERR will not 
inhibit this message; see Chapter 9) . 

A READ/WRITE operation was tried but no 
device handler was in memory for it. 

A user program with overlays failed to 
successfully read an overlay. 

A hard I/O error occurred while the 

system was attempting to write a user 
program to the system swap blocks . 
This is usually caused by a write- 
locked system device. Under the Single- 
Job Monitor, this may cause the system 
to halt. 



vn-SYS ERR 



An I/O error occurred while trying to 
read KMON/USR into memory, indicating 
that the monitor file is situated on the 
system device in an area that has 
developed one or more bad blocks . The 
monitor prints the message and loops 
trying to read KMON. The message is a 
warning that the system device is bad . 



January 197 6 
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If, after several seconds, it is 
apparent that attempts to read KMON are 
failing, halt the processor. It may be 
impossible to boot the volume because of 
the bad area in the monitor file. Use 
another system device to verify the bad 
blocks and follow the recovery procedures 
described in section 4.2.12.1 of Chapter 
4. 



?M-TRAP TO 4 
7M-TRAP TO 10 



The job has referenced illegal memory 
or device registers, an illegal instruc- 
tion was used, stack overflow occurred, 
a word instruction was executed with an 
odd address, or a hardware problem caused 
bus time-out traps through location 4. 



If CSI errors occur and input was from the console terminal, an error 
message is printed on the terminal. 



Message 
?DEV PUL? 
7FIL NOT FND? 
7ILL CMD? 
7ILL DEV? 



Meaning 
Output file will not fit. 
Input file was not found. 
Syntax error. 
Device specified does not exist. 



2.8.1 Monitor HALTS 

There are two HALT instructions in the RT-11 V02 monitors, one each in 
F/B and Single- Job. The Single- Job Monitor will halt only if I/O 
errors occur during swap operations to the system device. If the S/J 
Monitor halts, look for a write- locked system device. 

The F/B Monitor will halt if a trap to location 4 occurs or if I/O 
occurs while the system is performing critical operations from which 
it cannot recover. If the F/B Monitor halts, look for use of 
non-existent devices, traps from interrupt service routines, or 
user-corrupted queue elements. 

The monitor halts can be detected by their address, which is high in 
memory, above the resident base address (location 54) . 

When a monitor halt occurs, do not attempt to restart the system bv 
pressing CONTinue on the processor; the system must be rebooted. 
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CHAPTER 3 
TEXT EDITOR 



The Text Editor (EDIT) is used to create and modify ASCII source files 
so that these files can be used as input to other system programs such 
as the assembler or BASIC. Controlled by user commands from the 
keyboard, EDIT reads ASCII files from a storage device, makes 
specified changes and writes ASCII files to a storage device or lists 
them on the line printer or console terminal. EDIT allows efficient 
use of VT-11 display hardware, if this is part of the system 
configuration. 

The Editor considers a file to be divided into logical units called 
pages. A page of text is generally 50-60 lines long (delimited by 
form feed characters) and corresponds approximately to a physical page 
of a program listing. The Editor reads one page of text at a time 
from the input file into its internal buffers where the page becomes 
available for editing. Editing commands are then used to: 

Locate text to be changed, 

Execute and verify the changes, 

Output a page of text to the output file, 

List an edited page on the line printer or console terminal. 



3.1 CALLING AND USING EDIT 

To call EDIT from the system device type: 

R EDIT 

and the RETURN key in response to the dot (.) printed by the monitor. 
EDIT responds with an asterisk (*) indicating it is in command mode 
and awaiting a user command string. 

Type CTRL C to halt the Editor at any time and return control to the 
monitor. To restart the Editor type ,R EDIT or the .REENTER command 
in response to the monitor's dot. The contents of the buffers are 
lost when the Editor is restarted. 
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3.2 MODES OF OPERATION 

Under normal usage, the Editor operates in one of two different modes s 
Command Mode or Text Mode. In Command Mode all input typed on the 
keyboard is interpreted as commands instructing the Editor to perform 
some operation. In Text Mode all typed input is interpreted as text 
to replace, be inserted into, or be appended to the contents of the 
Text Buffer. 

Immediately after being loaded into memory and started, the Editor is 
in Command Mode. An asterisk is printed at the left margin of the 
console terminal page indicating that the Editor is waiting for the 
user to type a command. All commands are terminated by pressing the 
ALTMODE key twice in succession. Execution of commands proceeds from 
left to right. Should an error be encountered during execution of a 
command string, the Editor prints an error message followed by an 
asterisk at the beginning of a new line indicating that it is still in 
Command Mode and awaiting a legal command. The command in error (and 
any succeeding commands) is not executed and must be corrected and 
retyped. 

Text mode is entered whenever the user types a command which must be 
followed by a text string. These commands insert, replace, exchange, 
or otherwise manipulate text; after such a command has been typed, 
all succeeding characters are considered part of the text string until 
an ALTMODE is typed. The ALTMODE terminates the text string and 
causes the Editor to reenter Command Mode, at which point all 
characters are considered commands again. 

A special editing mode, called Immediate Mode, can be used whenever 
the VT-11 display hardware is running. This mode is described in 
Section 3.7.2. 



3.3 SPECIAL KEY COMMANDS 

The EDIT key commands are listed in Table 3-1. Control commands are 
typed by holding down the CTRL key while typing the appropriate 
character. 

Table 3-1 
EDIT Key Commands 



Key 



ALTMODE 



CTRL C 



Explanation 



Echoes $. A single ALTMODE terminates a text 
string. A double ALTMODE executes the command 
string. For example, 

+ GM0V ft, B$-1C<** 

Echoes at the terminal as tC and a carriage 
return. Terminates execution of EDIT commands, 
and returns to monitor Command Mode. A double 
CTRL C is necessary when I/O is in progress. The 
REENTER command may be used to restart the Editor, 
but the contents of the text buffers are lost. 



(continued on next page) 
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Table 3-1 (cont.) 
EDIT Key Commands 



Key 


Explanation 


CTRL 


Echoes to and a carriage return. Inhibits 
printing on the terminal until completion of the 
current command string. Typing a second CTRL 
resumes output. 


CTRL U 


Echoes tU and a carriage return. Deletes all the 
characters on the current terminal input line. 
(Equivalent to typing RUBOUT back to the beginning 
of the line.) 


RUBOUT 


Deletes character from the current line; echoes a 
backslash followed by the character deleted. Each 
succeeding RUBOUT typed by the user deletes and 
echoes another character. An enclosing backslash 
is printed when a key other than RUBOUT is typed. 
This erasure is done right to left up to the last 
carriage return/line feed combination. RUBOUT may 
be used in both Command and Text Modes. 


TAB 


Spaces to the next tab stop. Tab stops are 
positioned every eight spaces on the terminal; 
typing the TAB key causes the carriage to advance 
to the next tab position. 


CTRL X 


Echoes tX and a carriage return. CTRL X causes 
the Editor to ignore the entire command string 
currently being entered. The Editor prints a 
<CRXLF> and an asterisk to indicate that the user 
may enter another command. For example: 




*IRBCD 
EFQH"X 

* 




A CTRL U would only cause deletion of EFGH; 
CTRL X erases the entire command. 



3.4 COMMAND STRUCTURE 

EDIT commands fall into six general categories: 



Category 
Input/Output 



Pointer location 



Commands 

Edit Backup 

Edit Read 

Edit Write 

End File 

Exit 

List 

Next 

Read 

Verify 

Write 

Advance 

Beginning 

Jump 



Section 

3.6.1.3 

3.6.1.1 

3.6.1.2 

3.6.1.9 

3.6.1.10 

3.6.1.7 

3.6.1.6 

3.6.1.4 

3.6.1.8 

3.6.1.5 

3.6.2.3 
3.6.2.1 
3.6.2.2 
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Search 



Text modification 



Utility 



Immediate Mode 



Find 


3.6.3.2 


Get 


3.6.3.1 


Position 


3.6.3.3 


Change 


3.6.4.4 


Delete 


3.6.4.2 


exchange 


3.6.4.5 


Insert 


3.6.4.1 


Kill 


3.6.4.3 


Edit Console 


3.7.1 


Edit Display 


3.7.1 


Edit Lower 


3.6.5.6 


Edit Upper 


3.6.5.6 


Edit Version 


3.6.5.5 


Execute Macro 


3.6.5.4 


Macro 


3.6.5.3 


Save 


3.6.5.1 


Unsave 


3.6.5.2 


ALTMODE 


3.7.2 


CTRL D 


3.7.2 


CTRL G 


3.7.2 


CTRL N 


3.7.2 


CTRL V 


3.7.2 


RUB OUT 


3.7.2 



The general format for the first five categories of EDIT commands is : 
nCtext$ 
nC$ 



or 



where n represents one of the legal arguments listed in Table 3-2, C 
is a one- or two-letter command, and text is a string of successive 
ASCII characters. 

As a rule, commands are separated from one another by a single 
ALTMODE; however, if the command requires no text, the separating 
ALTMODE is not necessary. Commands are terminated by a single 
ALTMODE; typing a second ALTMODE begins execution. (ALTMODE is used 
differently when Immediate Mode is in effect; Section 3.7.2 details 
its use in this case.) 



The format of Display Editor commands is somewhat different from 
normal editing command format, and is described in Section 3.7. 



the 



3.4.1 Arguments 

An argument is positioned before a command letter and is used either 
to specify the particular portion of text to be affected by the 
command or to indicate the number of times the command should be 
performed. With some commands, this specification is implicit and no 
arguments are needed; other editing commands require an argument. 
Table 3-2 lists the formats of arguments which are used by commands of 
this second type. 
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Format 



Table 3-2 
Command Arguments 



Meaning 





/ 



n stands for any integer in the range -16 383 to 
+16383 and may, except where noted, be preceded by 
a + or -. If no sign precedes n, it is assumed to 
be a positive number. Whenever an argument is 
acceptable in a command, its absence implies an 
argument of 1 (or -1 if only the - is present) . 

refers to the beginning of the current line. 



/ refers to the end of text in 
Buffer. 



the current Text 



= is used with the J, D and C commands only and 
represents -n, where n is equal to the length of 
the last text argument used. 



The roles of all arguments are explained more specifically in 
following sections. 



3.4.2 Command Strings 

All EDIT command strings are terminated by two successive ALTMODE 
characters. Spaces, carriage returns and line feeds within a command 
string may be used freely to increase command readability but are 
ignored unless they appear in a text string. Commands used to insert 
text can contain text strings that are several lines long. Each line 
is terminated with a <CRXLF> and the entire command is terminated 
with a double ALTMODE. 



Several commands can be strung together and executed in sequence, 
example , 



For 



text object 



text object 



*BGHOV PC, R0*-2CR1*5KGCLR @R2** 



second 
command 



third 
command 



first command 



fifth 
command 



fourth 
command 



Execution of a command string begins when the double ALTMODE is typed 
and proceeds from left to right. Except when they are part of a text 
string, spaces, carriage return, line feed, and single ALTMODES are 
ignored. For example: 

*BGM0V R0*=CCLR R1*RV$* 
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may be typed as : 

+B$ GMOV R@* 
= CCLR Rl* 
R* V** 

with equivalent execution. 



3.4.3 The Current Location Pointer 

Most EDIT commands function with respect to a movable reference 
pointer which is normally located between the most recent character 
operated upon and the next character in the buffer. At any given time 
during the editing procedure, this pointer can be thought of as 
representing the current position of the Editor in the text. Most 
commands use tljis pointer as an implied argument. Commands are 
available for moving the pointer anywhere in the text, thereby 
redefining the current location and allowing greater facility in the 
use of other commands. 



3.4.4 Character- and Line-Oriented Command Properties 

Edit commands are line-oriented or character-oriented depending on the 
arguments they accept. Line-oriented commands operate on entire lines 
of text. Character-oriented commands operate on individual characters 
independent of what or where they are. 

When using character-oriented commands, a numeric argument specifies 
the number of characters that are involved in the operation. Positive 
arguments represent the number of characters in a forward direction 
(in relation to the pointer) , negative arguments the number of 
characters in a backward direction. Carriage return and line feed 
characters are treated the same as any other character. For example, 
assume the pointer is positioned as indicated in the following text (t 
represents the current position of the pointer) : 

MOV #VECT,R2<CRXLF> + 
CLR @R2<CRXLF> 

The EDIT command -2 J backs the pointer by two characters. 

MOV #VECT,R2 + <CRXLF> 

CLR @R2<CRXLF> 

The command 10J advances the pointer forward by ten characters and 
places it between the CR and LF characters at the end of the second 
line. 

MOV #VECT,R2<CRXLF> 
CLR @R2<CRXLF> 

Finally, to place the pointer after the "C" in the first line, a -14 J 
command is used. The J (Jump) command is explained in Section 3.6.2.2, 

MOV #VECT,R2<CRXLF> 
CLR @R2<CRXLF> 
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When using line-oriented commands, a numeric argument represents the 
number of lines involved in the operation. The Editor recognizes a 
line of text as a unit when it detects a <CRXLF> combination in the 
text. When the user types a carriage return, the Editor automatically 
inserts a line feed. Positive arguments represent the number of lines 
forward (in relation to the pointer) ; this is accomplished by counting 
carriage return/line feed combinations beginning at the pointer. So, 
if the pointer is at the beginning of a line, a line-oriented command 
argument of +1 represents the entire line between the current pointer 
and the terminating line feed. If the current pointer is in the 
middle of the line, an argument of +1 represents only the portion of 
the line between the pointer and the terminating line feed. 

For example, assume a buffer of: 

MOV :PC,RKCRXLF> 

ADD t #DRIV-.,Rl<CRXLF> 

MOV #VECT,R2<CRXLF> 

CLR @R2<CRXLF> 

The command to advance the pointer one line (1A) causes the following 
change : 

MOV PC,R1<CRXLF> 

+ ADD #DRIV-.,RKCRXLF> 

MOV #VECT,R2<CRXLF> 

CLR @R2<CRXLF> 

The command 2A moves the pointer over 2 <CRXLF> combinations: 

MOV PC,RKCRXLF> 

ADD #DRIV-.,RKCRXLF> 

MOV #VECT,R2<CRXLF> 

+CLR @R2<CRXLF> 

Negative line arguments reference lines in a backward direction (in 
relation to the pointer) . Consequently, if the pointer is at the 
beginning of the line, a line argument of -1 means "the previous line" 
(moving backward past the first <CRXLF> and up to but not including 
the second <CRXLF>; if the printer is in the middle of a line, an 
argument of -1 means the preceding 1 1/2 lines. Assume the buffer 
contains : 

MOV PC,R1<CRXLF> 

ADD #DRIV-.,R1<CRXLF> 

MOV #VECT,R2<CRXLF> 

CLR @R2<CRXLF> 

A command of -1A backs the pointer by 1 1/2 lines. 

MOV PC,RKCRXLF> 

l-ADD #DRIV-.,RKCRXLF> 

MOV #VECT,R2<CRXLF> 

CLR @R2<CRXLF> 
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Now a command of -1A backs it by only 1 line, 

+ MOV PC,RKCRXLF> 

ADD #DRIV-.,RKCRXLF> 

MOV #VECT,R2<CRXLF> 

CLR @R2<CRXLF> 



3,4.5 Command Repetition 

Portions of a command string may be executed more than once by 

enclosing the desired portion in angle brackets (<>) and preceding the 

left angle bracket with the number of iterations desired. The 
structure is: 

Cl$C2$n<C3$C4$>C5$$ 

where CI, C2,...C5 represent commands and n represents an iteration 
argument. Commands CI and C2 are each executed once, then commands C3 
and C4 are executed n times. Finally command C5 is executed once and 
the command line is finished. The iteration argument (n) must be a 
positive number (1 to 16,383), and if not specified is assumed to be 
1. If the number is negative or too large, an error message is 
printed. Iteration brackets may be nested up to 20 levels. Command 
lines are checked to make certain the brackets are correctly used and 
match prior to execution. 

Essentially, enclosing a portion of a command string in iteration 
brackets and preceding it with an iteration argument (n) is equivalent, 
to typing that portion of the string n times. For example: 

*BGfiflR*2<:-DIB*-J>V** 
is equivalent to typing: 

*BGfiRfi*-DIB*-J-C'IB*-J-DIB*-JV** 
and: 

*B3<2<RD>V>** 
is equivalent to typing: 

+ BRDfiDVfiDflC'VfiDfiDV$* 
The following bracket structures are examples of legal usage: 

The following bracket structures are examples of illegal combinations 
which will cause an error message since the brackets are not properly 
matched : 

XX 

During command repetition, execution proceeds from left to right until 
a right bracket is encountered. EDIT then returns to the last left 
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bracket encountered, decrements the iteration counter and executes the 
commands within the brackets. When the counter is decremented to 0, 
EDIT looks for the next iteration count to the left and repeats the 
same procedures. The overall effect is that EDIT works its way to the 
innermost brackets and then works its way back again. The most common 
use for iteration brackets is found in commands such as Unsave, that 
do not accept repeat counts. For example: 

Assume a file called SAMP (stored on device DK) is to be read and the 
first four occurrences of the instruction MOV #200, R0 on each of the 
first five pages are to be changed to MOV #244 ,R4. The following 
command line is entered: 



*EBSRMP*5<N4<BGM0V #2fifl, R0*=J*3<G0*=C4*>»EX** 



J 



The command line contains three sets of iteration loops (A,B,C) and is 
executed as follows : 

Execution initially proceeds from left to right; the file SAMP is 
opened for input, and the first page is read into memory. The pointer 
is moved to the beginning of the buffer and a search is initiated for 
the character string MOV #200, R0. When the string is found, the 
pointer is positioned at the end of the string, but the =J command 
moves the pointer back so that it is positioned immediately preceding 
the string. At this point, execution has passed through each of the 
first two sets of iteration loops (A,B) once. The innermost loop (C) 
is next executed three times, changing the 0s to 4s. Control now 
moves back to pick up the second iteration of loop B , and again moves 
from left to right. When loop C has executed three times, control 
again moves back to loop B. When loop B has executed a total of 4 
times, control moves back to the second iteration of loop A, and so 
forth until all iterations have been satisfied. 



3.5 MEMORY USAGE 



The memory area used by the Editor is divided into four logical 
buffers as follows : 



High Memory 



MACRO BUFFER 


SAVE 


BUFFER 


FREE 


MEMORY 


COMMAND INPUT 
BUFFER 


TEXT 


BUFFER 



Low Memory 
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The Text Buffer contains the current page of text being edited, and 
the Command Input Buffer holds the command currently being typed at 
the terminal. If a command currently being entered by the user is 
within 10 characters of exceeding the space available in the Command 
Buffer, the message: 

* CB ALMOST FULL * 

is printed. If the command can be completed within 10 characters, the 
user may finish entering the command; otherwise he should type the 
ALTMODE key twice to execute that portion of the command line already 
completed. The message is printed each time a character is entered in 
one of the last 10 spaces. 

If the user attempts to enter more than 10 characters the message: 

?CB FULL? 

is printed and all commands typed within the last 10 characters are 
ignored. The user again has 10 characters of available space in which 
to correct the condition. 

The Save Buffer contains text stored with the Save (S) command, and 
the Macro Buffer contains the command string macro entered with the 
Macro (M) command. (Both commands are explained in Section 3.6.5.) 

The Macro and Save Buffers are not allocated space until an M or S 
command is executed. Once an M or S command is executed, a 0M or 0U 
(Unsave) command must be executed to return that space to the free 
area. 

The size of each buffer automatically expands and contracts to 
accommodate the text being entered; if there is not enough space 
available to accommodate required expansion of any of the buffers, a 
"?*N0 ROOM*?" error message is typed. 



3.6 EDITING COMMANDS 



3.6.1 Input/Output Commands 

Input commands are used to create files and read them into the Text 
Buffer where they become available for editing or listing. Output 
commands cause text to be listed on the console terminal or line- 
printer or written out to a storage device. Some commands are 
specifically designed for either input or output functions, while a 
few commands serve both purposes. 

Once editing is completed and the page currently in the Text Buffer is 
written to the output file, that page of text is unavailable for 
further editing until the file is closed and reopened. 



3.6.1.1 Edit Read - The Edit Read command opens an existing file for 
input and prepares it for editing. Only one file can be open for input, 
at a time. 
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The form of the command is: 

ERdev : f ilnam. ext$ 

The. string argument (dev:f ilnam. ext) is limited to 19 characters and 
specifies the file to be opened. If no device is specified, DK: is 
assumed. If a file is currently open for input, that file is closed; 
any edits made to the file are preserved. 

Edit Read does not input a page of text nor does it affect the 
contents of the other user buffers (see Section 3.5.) 

Edit Read can be used on a file which is already open to close that 
file for input and reposition EDIT at its beginning. The first Read 
command following any Edit Read command inputs the first page of the 
file. 

Examples : 

*ERDT1:5RMP. MfiC** Opens SAMP. MAC on device DTI: for input. 

*ERS0URCE** Opens SOURCE on device DK: for input. 



3.6.1.2 Edit Write - The Edit Write command sets up a file for 
output of newly created or edited text. However, no text is output 
and the contents of the user buffers are not affected. Only one file 
can be open for output at a time. Any current output files are closed 

The form of the command is : 

EWdev :f ilnam. ext [n] $ 

The string argument (dev:f ilnam. ext [n] ) is limited to 19 characters 
and is the name to be assigned to the output file being opened. If 
dev: is not specified, DK: is assumed. [n] is optional and 

represents the length of the file to be opened. If not specified, one 
half the largest available space is used; if this is not adequate for 
the output file size, the EF and EX commands will not close the output 
file, and all edits will be lost. It is thus recommended that the [n] 
construction be used whenever there is doubt as to whether enough space 
is available on the device for the output file. 

If a file with the same name already exists on the device, the old file 
is deleted when an EXit, End File or another Edit Write command is 
executed . 



Examples : 



*EMDK : TEST. MRC$* Opens the file TEST. MAC on device DK: 

for output. 

*EWFILE. BflSC 11 ]** Opens the file FILE.BAS (allocating 11 

blocks) on the device DK: for output. 



3.6.1.3 Edit Backup - The Edit Backup command is used to open an 
existing file for editing and at the same time create a backup version 
of the file. Any currently open file will be closed. No text is read \ 
or written with this command. 
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The form of the command is : 

EBdev : f ilnam. ext [n] $ 

The device designation, filename and extension are limited to 19 

characters. If dev: is not specified, DK: is assumed. [n] is 

optional and represents the length of the file to be opened; if not 
specified, one-half the largest available space is used. 

The file indicated in the command line must already exist on the 
device designated since text will be read from this file as input. At 
the same time, an output file is opened under the same filename and 
extension. After an EB command has been successfully executed, the 
original file (used as input) is renamed with the current filename and 
a .BAK extension; any previous file with this filename and a .BAK 
extension is deleted. The new output file is closed and assigned the 
name as specified in the EB command. This renaming of files takes 
place whenever an Exit, End File, Edit Read, Edit Write or Edit Backup 
command is executed. 

Examples : 

*EBSV :BftSl. MAC** Opens BASl.MAC on SY. When editing is 

complete, the old BASl.MAC becomes 
BASl.BAK and the new file becomes 
BASl.MAC. Any previous version of 
BASl.BAK is deleted. 

+ EBBR52. BftSC15]$* Opens BAS2.BAS on DK (allocating 15 

blocks). When editing is complete, the 
old BAS2.BAS is labeled BAS2.BAK and the 
new file becomes BAS2.BAS. Any previous 
version of BAS2.BAK is deleted. 

In EB, ER and EW commands, leading spaces between the command and the 
filename are illegal (the filename is considered to be a text string) . 
All dev:file.ext specifications for EB, ER and EW commands conform to 
the RT-11 conventions for file naming and are identical to filenames 
entered in command strings used with other system programs. 



3.6.1.4 Read - The Read command (R) causes a page of text to be read 
from the input file (previously specified in an ER or EB command) and 
appended to the current contents, if any, of the Text Buffer. 

The form of the command is: 



No arguments are used with the R command and the pointer is not moved. 
Text is input until one of the following conditions is met: 

1. A form feed character, signifying the end of the page, is 
encountered. At this point, the form feed will be the last 
character in the buffer; or 
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2. The Text Buffer is within 500 characters of being full. 
(When this condition occurs. Read inputs up to the next 
<CRXLF> combination, then returns to Command Mode. An 
asterisk is printed as though the Read were complete, but 
text will not have been fully input) ; or 

3. An end-of-file condition is detected, (the *EOF* message is 
printed when all text in the file has been read into memory 
and no more input is available). 

The maximum number of characters which can be brought into memory with 
an R command is approximately 6,000 for an 8K system. Each additional 
4K of memory allows approximately 8,000 additional characters to be 
input. An error message is printed if the Read exceeds the memory 
available or if no input is available. 



3.6.1.5 Write - The Write command (W) moves lines of text from the 
Text Buffer to the output file (as specified in the EW or EB command) . 
The format of the command is : 

nW Write all characters beginning at the pointer and 
ending at the nth <CRXLF> to the output file. 

-nW Write all characters beginning on the -nth line and 
terminating at the pointer to the output file. 

0W Write the text from the beginning of the current line 
to the pointer. 

/W Write the text from the pointer to the end of the 
buffer. 

The pointer is not moved and the contents of the buffer are not 
affected. If the buffer is empty when the Write is executed, no 
characters are output. 

Examples : 



*5M$* 



Writes the next 5 lines of text starting 
at the pointer, to the current output 
file. 



*-2M** 



Writes the previous 2 lines of text, 
ending at the pointer, to the current 
output file. 



*B/W** 



Writes the entire Text Buffer 
current output file. 



to the 
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3.6.1.6 Next - The Next command acts as both an input and output 
command since it performs both functions. First it writes the current 
Text Buffer to the output file, then clears the buffer, and finally 
reads in the next page of the input file. The Next command can be 
repeated n times by specifying an argument before the command. The 
command format is : 

nN 

Next accepts only positive arguments (n) and leaves the pointer at the 
beginning of the buffer. If fewer than n pages are available in the 
input file, all available pages are input to the buffer, output to the 
current file, and deleted from the buffer; the pointer is left 
positioned at the beginning of an empty buffer, and an error message 
is printed. This command is equivalent to a combination of the 
Beginning, Write, Delete and Read commands (B/W/DR) . Next can be used 
to space forward, in page increments, through the input file. 



Example : 



*2N$$ Writes the contents of the current Text 

Buffer to the output file. Read and 
write the next page of text. Clear the 
buffer and then read in another page. 



3.6.1.7 List - The List command prints the specified number of lines 
on the console terminal. The format of the command is: 

nL Print all characters beginning at the 

pointer and ending with the nth 
<CRXLF>. 

-nL Print all characters beginning with the 

first character on the -nth line and 
terminating at the pointer. 

OL Print from the beginning of the current 

line up to the pointer. 

/L Print from the pointer to the end of the 

buffer. 

The pointer is not moved after the command is executed. 

Examples : 

*-2L** Prints all characters starting at the 

second preceding line and ending at the 
pointer. 

*4L** Prints all characters beginning at the 

pointer and terminating at the 4th 
<CRXLF>. 

Assuming the pointer location is : 

MOVB 5(R1),@R2 
ADD + R1,(R2) + 
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The command: 

Prints the previous 1 1/2 lines up to the pointers 

MOVB 5(R1),@R2 
ADD 



3.6.1.8 Verify - The Verify command prints the current text line 
(the line containing the pointer) on the terminal. The position of 
the pointer within the line has no effect and the pointer does not 
move . The command format is : 



No arguments are used. The V command is equivalent to a OLL (List) 
command. 



Example : 



*V** The command causes the current line of 

RDD Rl. <R2)+ text to be printed. 



3.6.1.9 End File - The End File command closes the current output 
file. This command does no input/output operations and does not move 
the pointer. The buffer contents are not affected. The output file 
is closed, containing only the text previously output. 

The form of the command is : 

EF 

No arguments are used. Note that an implied EF command is included in 
EW and EB commands. 



3.6.1.10 EXit - The EXit command is used to terminate editing, copy 
the text buffer and the remainder of the input file to the output file, 
close input and output files, and return control to the monitor. It 
performs consecutive Next commands until the end of the input file is 
reached, then closes both the input and output files. 

The command format is : 

EX 

No arguments are used. Essentially, Exit is used to copy the 
remainder of the input file into the output file and return to the 
monitor. Exit is legal only when there is an output file open. If an 
output file is not open and it is desired to terminate the editing 
session, return to the monitor with CTRL C. 



3-15 



Text Editor 



NOTE 

An EF or EX command is necessary in 
order to make an output file permanent. 
If CTRL C is used to return to the 
monitor without a prior execution of an 
EF command, the current output file is 
not saved. (It can however, be made 
permanent using the monitor CLOSE 
command; see Section 2.7.2.5.) 

An example of the contrasting uses of the EF and EX commands follows. 
Assume an input file, SAMPLE, contains several pages of text. The 
user wishes to make the first and second pages of the file into 
separate files called SAMl and SAM2, respectively; the remaining 
pages of text will then make up the file SAMPLE. This can be done 
using these commands: 

+ ERSflHPLE;r* 

*RNEF** 

♦EHSRM2** 

*NEF*$ 

fEWSRMPLEifEX** 



The user might note that the EF commands are not necessary in this 
example since the EW command closes a currently open output file 
before opening another. 



3.6.2 Pointer Relocation Commands 

Pointer relocation commands allow the current location pointer to be 
moved within the Text Buffer. 



3.6.2.1 Beginning - The Beginning command moves the current location 
pointer to the beginning of the Text Buffer. 

The command format is : 

B 

There are no arguments. 

For example, assume the buffer contains: 

MOVB 5(R1),@R2 

ADD R1,(R2)+ 

CLR &R2 

MOVB 6 t (Rl),@R2 
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The B command: 

moves the pointer to the beginning of the Text Buffer: 

+ MOVB 5(Rl),@R2 

ADD R1,(R2)+ 

CLR @R2 

MOVB 6(R1),@R2 



3.6.2.2 Jump - The Jump command moves the pointer over the specified 
number of characters in the Text Buffer. 

The form of the command is : 

(+ or -) nJ Move the pointer (backward or forward) n 

characters. 

OJ Move the pointer to the beginning of the current 
line (equivalent to OA) . 

/J Move the pointer to the end of the Text Buffer 
(equivalent to /A) . 

=J Move the pointer backward n characters, where n 
equals the length of the last text argument used. 

Negative arguments move the pointer toward the beginning of the 
buffer, positive arguments toward the end. Jump treats carriage 
return, line feed, and form feed characters the same as any other 
character, counting one buffer position for each. 



Examples : 



*3J$* Moves the pointer ahead three 

characters , 

*-4J** Moves the pointer back four characters. 

*B$GRBC*=J$* Move the pointer so that it immediately 

precedes the first occurrence of 'ABC' 
in the buffer. 



3.6.2.3 Advance - The Advance command is similar to the Jump command 
except that it moves the pointer a specified number of lines (rather 
than single characters) and leaves it positioned at the beginning of 
the line. 

The form of the command is : 

nA Advance the pointer forward n lines and 

position it at the beginning of the nth 
line. 
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-nA Move the pointer backward past n 

<CRXLF> combinations and position it at 
the beginning of the -nth line. 

OA Advance the pointer to the beginning of 

the current line (equivalent to OJ) . 

/A Advance the pointer to the end of the 

Text Buffer (equivalent to /J) . 

Examples : 

*3R** Moves the pointer ahead three lines. 

Assuming the buffer contains : 

CLR @R2 

■f 

The command: 

Moves the pointer to: 
+ CLR @R2 



3.6.3 Search Commands 

Search commands are used to locate specific characters or strings of 
characters within the Text Buffer. 



3.6.3.1 Get - The Get command starts at the pointer and searches the 
current Text Buffer for the nth occurrence of a specified text string. 
If the search is successful, the pointer is left immediately following 
the nth occurrence of the text string. If the search fails, an error 
message is printed and the pointer is left at the end of the Text 
Buffer. The format of the command is : 

nGtext$ 

The argument (n) must be positive and is assumed to be 1 if not 
otherwise specified. The text string may be any length and 
immediately follows the G command. The search is made on the portion 
of the text between the pointer and the end of the buffer. 

Example : 

Assuming the buffer contains : 



iMOV 


PC,R1 


ADD 


#DRIV-.,R1 


MOV 


#VECT,R2 


CLR 


@R2 


MOVB 


5(R1) ,@R2 


ADD 


R1,(R2)+ 


CLR 


@R2 


MOVB 


6(R1),@R2 
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The command: 

*GRDD$* 
positions the pointer at: 

ADD. #DRIV-. ,R1 
The command: 

*3G@R2*$ 
positions the pointer at: 

ADD R1,(R2)+ 

CLR @R2 + 

After search commands, the pointer is left immediately following the 
text object. Using a search command in combination with =J will place 
the pointer before the text object, as follows: 

*GTEST*=J** 
This command combination places the pointer before 'TEST'. 



3.6.3.2 Find - The Find command starts at the current pointer and 
searches the entire input file for the nth occurrence of the text 
string. If the nth occurrence of the text string is not found in the 
current buffer, a Next command is automatically performed and the 
search is continued on the new text in the buffer. When the search is 
successful, the pointer is left immediately following the nth 
occurrence of the text string. If the search fails (i.e., the 
end-of-file is detected for the input file and the nth occurrence of 
the text string has not been found) , an error message is printed and 
the pointer is left at the beginning of an empty Text Buffer. 

The form of the command is : 

nFtext$ 

The argument (n) must be positive and is assumed to be 1 if not 
otherwise specified. 

By deliberately specifying a nonexistent search string, the user can 
close out his file; that is, he can copy all remaining text from the 
input file to the output file. 

Find is a combination of the Get and Next commands. 

Example: 

* 2 F M V B GCRl), @R2$* Searches the entire input file for 

the second occurrence of the text 
string MOVB 6(R1),@R2. Each 
unsuccessfully searched buffer is 
written to the output file. 
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3.6.3.3 Position - The Position command searches the input file for 
the nth occurrence of the text string. If the desired text string is; 
not found in the current buffer, the buffer is cleared and a new pages 
is read from the input file. The format of the command is: 

nPtext$ 

The argument (n) must be positive, and is assumed to be 1 if not 
otherwise specified. When a P command is executed the current 
contents of the buffer are searched from the location of the pointer 
to the end of the buffer. If the search is unsuccessful, the buffer 
is cleared and a new page of text is read and the cycle is continued. 

If the search is successful, the pointer is positioned after the nth 
occurrence of the text. If it is not, the pointer is left at the 
beginning of an empty Text Buffer. 

The Position command is a combination of the Get, Delete and Read 
commands; it is most useful as a means of placing the location 
pointer in the input file. For example, if the aim of the editing 
session is to create a new file from the second half of the input 
file, a Position search will save time. 

The difference between the Find and Position commands is that Find 
writes the contents of the searched buffer to the output file while 
Position deletes the contents of the buffer after it is searched. 



Example : 



*PflDD Rl, <R2>+** 



Searches the entire input file for the 
specified string ignoring the 
unsuccessfully searched buffers. 



3.6.4 Text Modification Commands 

The following commands are used to insert, relocate, and delete text, 
in the Text Buffer. 



3.6.4.1 Insert - The Insert command causes the Editor to enter Text 
Mode and allows text to be inserted immediately following the pointer. 
Text is inserted until an ALTMODE is typed and the pointer is 
positioned immediately after the last character of the insert. The 
command format is : 

Itext$ 

No arguments are used with the Insert command, and the text string is 
limited only by the size of the Text Buffer and the space available. 
All characters except ALTMODE are legal in the text string. ALTMODE 
terminates the text string. 

NOTE 

Forgetting to type the I command will 
cause the text entered to be executed as 
commands . 
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EDIT automatically protects against overflowing the Text Buffer during 
an Insert. If the I command is the first command in a multiple 
command line, EDIT ensures that there will be enough space for the 
Insert to be executed at least once. If repetition of the command 
exceeds the available memory, an error message is printed. 



Example : 



*IMOV 
MOV 
MOVB 
* 



#BUFF, R2 
#LINE, Rl 
-1<R2>, R@** 



Inserts the specified text at 
the current location of the 
pointer and leaves the pointer 
positioned after RO. 



3.6.4.2 Delete - The Delete command removes a specified number of 
characters from the Text Buffer. Characters are deleted starting at 
the pointer; upon completion, the pointer is positioned at the first 
character following the deleted text. 



The form of the command is : 
(+ or -) nD 

OD 

/D 



Delete n characters (forward or backward 
from the pointer) . 

Delete from beginning of current line to 
the pointer (equivalent to OK) . 



Delete from pointer to end 
Buffer (equivalent to /K) . 



of Text 



=D 



Examples : 



!D*$ 



*B*FH0V R1$=D* 



Delete -n characters, where n equals the 
length of the last text argument used. 



Deletes the two characters immediately 
preceding the pointer. 

Deletes the text string 'MOV Rl'. (=D 
used in combination with a search 
command will delete the indicated text 
string) . 



Assuming a buffer of: 



ADD 
CLR 


R1,(R2)+ 

+@R2 


the command: 




*0D*J 




leaves the buffer 


with: 


ADD 

+ @R2 


R1,(R2)+ 
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3.6.4.3 Kill - The Kill command removes n lines from the Text 
Buffer. Lines are deleted starting at the location pointer? upon 
completion of the command, the pointer is positioned at the beginning 
of the line following the deleted text. The command format is: 



Example : 



nK 



-nK 



OK 



/K 



*2K«* 



Delete lines beginning at the pointer 
and ending at the nth <CR><LF>. 

Delete lines beginning with the first 
character in the -nth line and ending at 
the pointer. 

Delete from the beginning of the current 
line to the pointer (equivalent to OD) ., 



Delete from the pointer to the end 
the Text Buffer (equivalent to /D) . 



of 



Delete lines starting at the current 
location pointer and ending at the 2nd 
<CRXLF>. 



Assuming a buffer of; 



ADD 

CLRi 

MOVB 


Rl, (R2)+ 

@R2 

6(R1) ,@R2 


the command : 




*/K*$ 




alters the contents 


of the buffer to: 


ADD 
CLR+ 


Rl, (R2)+ 



Kill and Delete commands perform the same function, except that Kill 
is line-oriented and Delete is character-oriented. 



3.6.4.4 Change - The Change command replaces n characters, starting 
at the pointer, with the specified text string and leaves the pointer 
positioned immediately following the changed text. 

The form of the command is: 



(+ or -) nCtext$ 
OCtext$ 

/Ctext$ 



Replace n characters (forward or backward from the 
pointer) with the specified text. 

Replace the characters from the beginning of the 
line up to the pointer with the specified text 
(equivalent to OX) . 

Replace the characters from the pointer to the end 
of the buffer with the specified text (equivalent 
to /X). 
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=Ctext$ Replace -n characters with the indicated text 
string, where n represents the length of the last 
text argument used. 

The size of the text is limited only by the size of the Text Buffer 
and the space available. All characters are legal except ALTMODE 
which terminates the text string. 

If the C command is to be executed more than once (i.e., it is 

enclosed in angle brackets) and if there is enough space available so 

that the command can be entered, it will be executed at least once 

(provided it appears first in the command string) . If repetition of 

the command exceeds the available memory, an error message is printed. 

The Change command is identical to executing a Delete command followed 
by an Insert (nDItext$) . 



Examples : 



*5C#VECT$* Replaces the five characters to the 

right of the pointer with #VECT. 



Assuming a buffer of: 







CLR 
MOV + 


@R2 
5(R1) 


,@R2 


The 


command : 










*0CHDD6*$ 






leaves 


the buffer with: 








CLR 
ADDB+ 


<§R2 
5(R1) 


,@R2 



=C can be used in conjunction with a search command to replace a 
specific text string as follows : 

*GFIFTV : $=CFI VE : * Find the occurrence of the text string 

FIFTY: and replace it with the text 
string FIVE:. 



3.6.4.5 Exchange - The Exchange command exchanges n lines, beginning 
at the pointer, with the indicated text string and leaves the pointer 
positioned after the changed text. 

The form of the command is : 

nXtext$ Exchange all characters beginning at the pointer 
and ending at the nth <CRXLF> with the indicated 
text. 

-nXtext$ Exchange all characters beginning with the first 
character on the -nth line and ending at the 
pointer with the indicated text. 

OXtext$ Exchange the current line from the beginning to 
the pointer with the specified text (equivalent to 
OC). 
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/Xtext$ Exchange the lines from the pointer to the end of 
the buffer with the specifed text (equivalent to 
/C). 



All characters are legal in 
terminates the text. 



the text string except ALTMODE which 



The Exchange command is identical to a Kill command followed by 
Insert (nKItext$) , and accepts all legal line-oriented arguments. 



sin 



If the X command is enclosed within angle brackets so that it will be 
executed more than once, and if there is enough memory space available 
so that the X command can be entered, it will be executed at least 
once (provided it is first in the command string) . If repetition of 
the command exceeds the available memory, an error message is printed. 



Example ; 



*2XflDD 
CLR 

* 



Rl. <(?£> + 
@R2 



Exchanges the two lines to 
the right of the pointer location 
with the text string. 



3.6.5 Utility Commands 



3.6.5.1 Save - The Save command starts at the pointer and copies the 
specified number of lines into the Save Buffer (described previously 
in Section 3.5) . 

The form of the command is : 

nS 

The argument (n) must be positive. The pointer position does not 

change and the contents of the Text Buffer are not altered. Each time 

a Save is executed, the previous contents of the Save Buffer, if any, 

are destroyed. If the Save command causes an overflow of the Save 
Buffer, an error message is printed. 

Example : 

Assume the Text Buffer contains the following assembly language 
subroutine : 
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SUBROUTINE MSGTYP 

;WHEN CALLED, EXPECTS RO TO POINT TO AN 
; ASCII MESSAGE THAT ENDS IN A ZERO BYTE, 
;TYPES THAT MESSAGE ON THE USER TERMINAL 





.ASECT 




.=1000 


MSGTYP : 


TSTB (%0) ;DONE? 




BEQ MDONE ; YES-RETURN 


MLOOP : 


TSTB @#177564 ;NO-IS TERMINAL READY? 




BPI. MLOOP ; NO-WAIT 




MOVB (%0)+,@#177566 ;YES PRINT CHARACTER 




BR MSGTYP ;LOOP 


MDONE : 


RTS %7 ; RETURN 


The command: 




*14S$* 





stores the entire subroutine in the Save Buffer; it may then 
inserted in a program wherever needed by using the U command. 



be 



3.6.5.2 Unsave - The Unsave command inserts the entire contents of 
the Save Buffer into the Text Buffer at the pointer location and 
leaves the pointer positioned following the inserted text. 

The form of the command is : 

U Insert in the Text Buffer the contents of the Save 
Buffer. 

0U Clear the Save Buffer and reclaim the area for text. 

Zero is the only legal argument to the U command. 

The contents of the Save Buffer are not destroyed by the Unsave 
command (only by the 0U command) and may be Unsaved as many times as 
desired. 

If there is no text in the Save Buffer and the U command is given, the 
?*NO TEXT*? error message is printed. If the Unsave command causes 
an overflow of the Text Buffer, the ?*NO ROOM*? error message is 
displayed. 



3.6.5.3 Macro - The Macro command inserts a command string into the 
EDIT Macro Buffer. The Macro command is of the form: 

M/command string/ Store the command string in the Macro 

Buffer. 



or 



0M 
M// 



Clear the Macro Buffer and reclaim the 
area for text. 



/represents the delimiter character. The delimiter is always the 
first character following the M command, and may be any character 
which does not appear in the Macro command string itself. 
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Starting with the character following the delimiter, EDIT places the 
Macro command string characters into its internal Macro Buffer until 
the delimiter is encountered again. At this point, EDIT returns to 
Command Mode. The Macro command does not execute the Macro string; 
it merely stores the command string so that it can be executed later 
by the Execute Macro (EM) command. Macro does not affect the contents 
of the Text or Save Buffers. 

All characters except the delimiter are legal Macro command string 
characters, including single ALTMODEs to terminate text commands. 
All commands, except the M and EM commands, are legal in a command 
string macro. 

In addition to the OM command, typing the M command immediately 
followed by two identical characters (assumed to be delimiters) and 
two ALTMODE characters also clears the Macro Buffer. 

Examples : 

*M /,-'$* Clears the Macro Buffer 

*M,-'GR@* -CI $/$$ Stores a Macro to change RO to Rl. 

NOTE 

Be careful to choose infrequently used 
characters as macro delimiters; use of 
frequently used characters can lead to 
inadvertent errors. For example, 

*M GMOV R0*=CRDD Rl* **■ 
?*N0 FILE*? 

In this case, it was intended that the 
macro be GMOV R0$=CADD Rl$ but since the 
delimiter character (the character 
following the M) is a space, the space 
following MOV is used as the second 
delimiter, terminating the macro. EDIT 
then returns an error when the R0$= 
becomes an illegal command structure. 



3.6.5.4 Execute Macro - The Execute Macro command executes the 
command string specified in the last Macro command. 

The form of the command is : 

nEM 

The argument (n) must be positive. The macro is executed n times and 
returns control to the next command in the original command string. 
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Examples : 



*B1000EM$* 

?*SRCH FAIL IN MACRO*' 

* 



Executes the MACRO stored in 
the previous example. An error 
message is returned when the 
end of buffer is reached. 
(This macro effectivelychanges 
all occurrences of RO in the 
Text Buffer to Rl.) 



+IM0V PC, R1*2EHICLR @R2*$ 



In a new program, inserts 
MOV PC,R1 then executes the 
command in the Macro Buffer 
twice before inserting CLR 

@R2. 



3.6.5.5 Edit Version - The Edit Version command displays the version 
number of the Editor in use on the console terminal. 

The form of the command is: 

EV$ 

Example : 

*ev** 

V82-01 



3.6.5.6 Upper- and Lower->Case Commands - Users who have any upper/ 
lower-case terminal as part of their hardware configuration may take 
advantage of the upper- and lower-case capability of this terminal. 
Two editing commands, EL and EU, permit this. 

When the Editor is first called (R EDIT) , upper-case mode is assumed; 
all characters typed are automatically translated to upper case. To 
allow processing of both upper- and lower-case characters, the Edit 
Lower command is entered: 

*fc. !...*» 

Xf.i. Text and commands can be entered in UPPER and lower c a se.il>* 

* 

The Editor now accepts and echoes upper- and lower-case characters 
received from the keyboard, and outputs text on the teleprinter in 
upper- and lower-case. 

To return to upper-case mode, the Edit Upper command is used: 

Control also reverts to upper-case mode upon exit from the Editor (via 
EF, EX, or CRTL C) . 
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Note that when an EL command has ceen issued, Edit commands can be en- 
tered in either upper- or lower-case. Thus, the following two commands 
are equivalent: 

* G T E X T * == C n «s w t e :•: t * M * * 

* si T E X T * :::: enew tsx t * v * * 

The Editor automatically translates (internally) all commands to upper- 
case independent of EL or EU. 



3.7 THE DISPLAY EDITOR 

In addition to all functions and commands mentioned thus far, the 
Editor has additional capabilities to allow efficient use of VT-11 
display hardware which may be part of the system configuration (GT40, 
GT44, DECLAB 11/40). 

The most apparent feature is the ability to use the display screen 
rather than the console terminal as a window into the Text Buffer for 
printout of all textual input and output. When all the features of 

the display Editor are in use, a 12" screen displays text as shown in 
Figure 3-1: 



10 PRECEDING/ 
LINES OF TEXT\ 



CURSOR b^ 
(CURRENT LINE) _ 



AND 9 FOLLOWING/ 
LINES OF TEXT\ 



SEPARATION LINE- 

3 PRECEDING/" 
COMMAND LINESl. 

CURRENT COMMAND, 
LINE 









;get rn input line 


SWREG 






nov 




rrcNT.BB 


;«nv reserved rrs? 


6E3 




3U 


:no 


ADD 




SB. PBGNUH 


!VES. UPDATE PAGE NUMBER 


MOi; 




t-l.PflGEXT 




CLR 




LINNUM 


UNIT NEW CREr SEOUENCE 


CLR 




rrcNT 




CLR 




SEQEND 




TST 




BBSS 




BEG 




311 




CLR 




LPPCNT 




(W 




ILINBUF.RB 




!W 




K. LCBEGL 


:SET UP BEGINNING 


NOV 




tLINEND.LCENDL 


IfIND END or LINE MARKERS 


.ir 


NDr 


XSHL 




TST 




SHUNT 


;IH SVSTEM MACRO? 


SHE 




401 


:VES. SPECIAL 


.EHDC 






.ir 


HDr XHflCFO 





WINDOW 
\INTO THE 
'TEXT BUFFER 



«rascorc.nc»» 

»1 



Figure 3-1 
Display Editor Format 



January 1976 
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The major advantage is that the user can now see immediately where the 
pointer is. The pointer appears between characters on the screen as a 
bright blinking L-shaped cursor and can be detected easily and 
quickly. Note that if the pointer is placed between a carriage return 
and line feed, it appears in an inverted position at the beginning of 
the next line. 

In addition to displaying the current line (the line containing the 
cursor) , the 10 lines of text preceding the current line and the 9 
lines following it are also in view. Each time a command string is 
executed (via a double ALTMODE) this portion of the screen is 
refreshed so that it reflects the results of the commands just 
performed. 

The lower section of the screen contains 4 lines of editing commands. 
The command line currently being entered is last, preceded by the 
three most recent command lines. This section is separated from the 
text portion of the screen by a horizontal line of dashes. As new 
command lines are entered, previous command lines are scrolled upward 
off the command section so that only four command lines are ever in 
view. 

A 17" screen displays 30 lines of text and 8 command lines. 



3.7.1 Using the Display Editor 

The display features of the Editor are automatically invoked whenever 
the system scroller is in use and the user types: 

. R EDIT 

However, if the system does not contain VT-11 display hardware, the 
display features are not enabled. 

Providing that the system does contain VT-11 display hardware and that 
the user wishes to employ the screen during the editing session, he 
may activate it in one of two ways (all editing commands and functions 
previously discussed in this chapter are valid for use) : 

1. If the scroller is in use (i.e., the GT ON monitor command 
has been typed prior to calling the Editor) , EDIT recognizes 
this and automatically continues using the screen for display 
of text and commands. However, it rearranges the scroller so 
that a "window" into the Text Buffer appears in the top 
two/thirds of the screen, while the bottom third is used to 
display command lines. This arrangement is shown in Figure 
3-1. 

The Edit Console command can be used to return the scroller 
to its normal mode so that text and commands appear as 
described in Chapter 2, Section 2.7.1 (i.e., using the full 
screen for display of command lines, and eliminating the 
window) . The form of the command is : 

EC 
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For example: 

*BREC2L** The second and third lines of the 
current buffer are listed on the screen; 
there is no window into the Text Buffer 
at this point. 

Subsequent EC commands are ignored if the window into the 
Text Buffer is not being displayed. 

To recall the window, the Edit Display command is used: 

ED 

The screen is again arranged as shown in Figure 3-1. 

2. Assume the> scroller is not in use (i.e., the GT ON command 
has not been typed, or the monitor GT OFF command has been 
typed prior to calling the Editor) . When the user calls EDIT, 
an asterisk appears on the console terminal as described in 
Section 3.1. Using the ED command at this time provides the 
window into the Text Buffer; however, commands continue to 
be echoed to the console terminal. 

When ED is used in this case, it must be the first command 
issued; otherwise, it becomes an illegal command (since the 
memory used by the display buffer and code, amounting to over 
600 words, is reclaimed as working space). The display cannot 
be used again until a fresh copy of EDIT is loaded. 

While the display of the text window is active, ED commands 
are ignored. 

Typing the EC command clears the screen and returns all 
output to the console terminal. 

NOTE 

Under the Single- Job Monitor only, after 
the editing session is over, it is 
recommended that the screen be cleared 
by either typing the EC command, or 
returning to the monitor and using the 
monitor INITIALIZE command. Failure to 
do this may cause unpredictable results. 



3.7.2 Setting the Editor to Immediate Mode 

An additional mode is available in EDIT to provide an easier and 
faster degree of interaction during the editing session. This mode is 
called Immediate Mode and combines the most-used functions of the Text 
and Command Modes — namely, to reposition the pointer and to delete and 
insert characters. 

Immediate Mode may be used only when the VT-11 display hardware ia 
active and the Editor is running; it is entered by typing two 
ALTMODES (only) in response to the Command Mode asterisk: 

*$$ 
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The Editor responds by echoing an exclamation point on the screen. 
The exclamation character remains on the screen as long as control 
remains in Immediate Mode. 

Once Immediate Mode has been entered, only the commands in Table 3-3 
are u«efl. None of these commands echoes, but the text appearing on the 
screen is constantly refreshed and updated during the editing process. 
Note that no EDIT commands other than those in Table 3-3 may be used 
while control remains in Immediate Mode. 

To return control to the display Editor's normal Command Mode at any 
time while in Immediate Mode, type a single ALTMODE. The Editor 
responds with an asterisk and the user may proceed using all normal 
Editing commands. (Immediate Mode commands typed at this time will be 
accepted as Command Mode input characters.) To return control to the 
monitor while in Immediate Mode, type CTRL C. 



Table 3-3 
Immediate Mode Commands 



Command 


Meaning 


CTRL N 
CTRL G 

CTRL D 
CTRL V 

RUBOUT 

CTRL C 

ALTMODE (one only) 
(two) 

Any other character 
than those above 


Advance the pointer (cursor) to the 
beginning of the next line (equivalent 
to A). 

Move the pointer (cursor) to the 
beginning of the previous line 
(equivalent to -A) . 

Move the pointer (cursor) forward by one 
character (equivalent to J), 
Move the pointer (cursor) back by one 
character (equivalent to -J) . 

Delete the character immediately 
preceding the pointer (cursor) 
(equivalent to -D) . 

Return control to the monitor. 

Return control to Command Mode. 
Direct control to Immediate Mode. 

Insert the character as text positioned 
immediately before the pointer (cursor) 
(equivalent to I) . 
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3.8 EDIT EXAMPLE 



The following example illustrates the use of some of the EDIT commands 
to change a program stored on the device DK. Sections of the terminal 
output are coded by letter and corresponding explanations follow the 
example. 



. R EDIT 

*ERDK:TEST1. MfiCf* 
*EWDK: TESTS. MRC** 
*R$* 

TEST PROGRAM 



B 



STRRT : MOV #1000, V.6 
MOV # MSG, 20 
JSR %7hMSGTYP 
HRLT 
MSG : . ASCI I /IT WORK: 
. BVTE 15 
BVTE 12 
BVTE 



INITIRLI 
POINT R6 
PRINT 
STOP 



IE. STACK 
TO MESSAGE 



IT 



C {*B 1J 5D$* 
♦GPROQRflM** 
*8L** 
; PROGRAM*! TO 



( 






H < 



TEST SUBROUTINE 
; "THE TEST PR0GRRM WORKS" 
,UN THfc. TEMI\IM\RMINAL** 
*F. RSCII/** 

*8CTHE TEST PROGRAM WORKS** 
*P. BVTE'X 
*F. BVTE &$V$$ 

. BVTE 
*I 

. END 

PROGRAM TO TEST SUBROUTINE MSGTVP 
"THE TEST PROGRAM WORKS" 
ON THE TERMINAL 



MSGTVP. TVPES 



TVPES 



START: MOV #1000, K6 

MOV #MSfi, •<■:& 

JSR %7»MSGTYP 

HALT 
MSG: . ASCII/THE TEST 

. BVTE 15 

. BVTE 12 

. BVTE 8 

. END 



; INITIALIZE STACK 

; POINT R0 TO MESSAGE 

i PRINT IT 

; STOP 

PROGRAM WORKS/ 



*EX** 
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A The EDIT program is called and prints an *. The input file is 
TEST1.MAC; the output file is TEST2.MAC and the first page of 
input is read. 

B The buffer contents are listed. 

C Be sure the pointer is at the beginning of the buffer. Advance 
pointer one character (past the ;) and delete the "TEST ". 

D Position pointer after PROGRAM and verify the position by listing 
up to the pointer. 

E Insert text. RUBOUT used to correct typing error. 

F Search for .ASCII/ and change "IT WORKS" to "THE TEST PROGRAM 
WORKS". 

G CTRL X typed to cancel P command. Search for ".BYTE 0" and 
verify location of pointer with V command. 

H Insert text. Return pointer to beginning of buffer and list 
entire contents of buffer. 

I Close input and output files after copying the current text 
buffer as well as the rest of input file into output file. EDIT 
returns control to the monitor. 



3.9 EDIT ERROR MESSAGES 

The Editor prints an error message whenever one of the error 
conditions listed next occurs. Prior to executing any commands, the 
Editor first scans the entire command string for errors in command 
format (illegal arguments, illegal combinations of commands, etc.). If 
an error of this type is found, an error message of the form: 

7ERROR MSG? 

is printed and no commands are executed. The user must retype the 
command. 

If the command string is syntactically correct, execution is started. 
Execution errors are still possible, however (buffer overflow, I/O 
errors, etc.), and if such an error occurs, a message of the form: 

?*ERROR MSG*? 

is printed. In this case, all commands preceding the one in error are 
executed, while the command in error and those following are not 
executed. Most errors will generally be of the syntax type and can be 
corrected before execution. 
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When an error occurs during execution of a Macro, the message format 
is: 

?message IN MACRO? 

or 

?*raessage IN MACRO*? 

depending on when it is detected. 



Message 

*CB ALMOST FULL* 

?CB FULL? 

?*DIR FULL*? 
?*EOF*? 

?*FILE FULL*? 

?*FILE NOT FND*? 
?*HDW ERR*? 
?ILL ARG? 

?ILL CMD? 

?*ILL DEV*? 

?ILL MAC? 



Explanation 

The command currently being entered is within 
10 characters of exceeding the space 
available in the Command Buffer. 

Command exceeds the space allowed for a 
command string in the Command Buffer. 

No room in device directory for output file. 

Attempted a Read, Next or file searching 
command and no data was available. 

Available space for an output file is full. 
Type a CTRL C and the CLOSE monitor command 
to save the data already written. 



Attempted to open 
editing. 



a nonexisting file for 



A hardware error occurred during I/O. May be 
caused by WRITE LOCKed device. Try again. 

The argument specified is illegax for the 
command used. A negative argument was 
specified where a positive one was expected 
or argument exceeds the range + or - 16,383. 

EDIT does not recognize the command 

specified; ED was not the first command 

issued when used to activate the display 
hardware . 

Attempted to open a file on an illegal 
device, or attempted to use display hardware 
when none was available (it may be in use by 
the other job) . 

Delimiters were improperly used, or an 
attempt was made to enter an M command during 
execution of a Macro or an EM command while 
an EM was in progress. 
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Message 

?*ILL NAME*? 

?*N0 FILE*? 
?*N0 ROOM*? 



?*NO TEXT*? 
?*SRCH FAIL*? 

?"<> H ERR? 



Explanation 



File name specified 
illegal. 



in EB, EW, or ER is 



Attempted to read or write when no 
open. 



file is 



Attempted to Insert, Save, Unsave, Read, 
Next, Change or Exchange when there was not 
enough room in the appropriate buffer. 
Delete unwanted buffers to create more room 
or write text to the output file. 

Attempted to call in text from the Save 
Buffer when there was no text available. 

The text string specified in a Get, Find or 
Position command was not found in the 
available data. 

Iteration brackets are nested too deeply or 
used illegally or brackets are not matched. 



3-35 



CHAPTER 4 
PERIPHERAL INTERCHANGE PROGRAM (PIP) 



The Peripheral Interchange Program (PIP) is the file transfer and 
maintenance utility for RT-11. PIP is used to transfer files between 
any of the RT-11 devices (listed in Table 2-2) , merge and delete files 
from these devices, and list, zero, and compress device directories. 



4.1 CALLING AND USING PIP 

To call PIP from the system device type: 

R PIP 

in response to the dot printed by the Keyboard Monitor. The Command 
String Interpreter prints an asterisk at the left margin of the 
terminal and waits to receive a line of filenames and command 
switches. PIP accepts up to six input filenames and three output 
filenames; command switches are generally placed at the end of the 
command string but may follow any filename in the string. There is no 
limit to the number of switches which may be indicated in a command 
line, as long as only one operation (insertion, deletion, etc.) is 
represented. 

Since PIP performs file transfers for all RT-11 data formats (ASCII, 
object, and image) there are no assumed extensions for either input or 
output files; all extensions, where present, must be explicitly 
specified. 

Following completion of a PIP operation, the Command String 
Interpreter prints an asterisk at the left margin of the teleprinter 
and waits for another PIP command line. Typing CTRL C at any time 
returns control to the Keyboard Monitor. To restart PIP, type R PIP 
or the REENTER command in response to the monitor's dot. 



4.1.1 Using the "Wild Card" Construction 

PIP follows the standard file specification syntax explained in 
Section 2.5 (Chapter 2) with one exception: the asterisk character 
can be used in a command string to represent filenames or extensions. 
The asterisk (called the "wild card") in a file specification means 
"all". For instance, "*.MAC" means all files with the extension .MAC. 
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regardless of filename. "FORTN.*" means all files with the filename 
FORTN regardless of extension. "*.*" means all files, regardless of 
name or extension. 

The wild card character is legal in the following cases only (switches 
are explained in the next section) : 

1. Input file specification for the copy and multiple copy 
operations (i.e., no switch, /I, /B, and /A). 

2. File specification for the delete operation (/D) . 

3. Input and output file specifications for the rename operation 
(/R). 

4. Input and output file specifications for the multiple copy 
operation (/X) . 

5. Input file specifications for the directory list operations 
(/L, /E, /F). 

Operations on files implied by the wild card asterisk are performed in 
the order in which the files appear in the directory. System files 
with the extension .SYS and files with bad blocks and the extension 
.BAD are ignored when the wild card character is used unless the /Y 
switch is specified. 



Examples : 



**. BRK/D Causes all files with the extension .BAR 

(regardless of their filenames) to be 
deleted from the device DK. 

**. TST=*. BflK/R Renames all files with a .BAK extension 

(regardless of filenames) so that these 
files now have a .TST extension 
(maintaining the same filenames) . 

*RKi:*.*/X/Y"=*.* Transfers all files, including system 

files, (regardless of filename or 
extension) from device DK to device RK1. 

**.MAC»*.OB..J/L Lists all files with .MAC and .OBJ 

extensions . 



4.2 PIP SWITCHES 

The various operations which can be performed by PIP are summarized in 
Table 4-1. If no switch is specified, PIP assumes the operation ia a 
file transfer in image (/I) mode. Detailed explanations of the 
switches follow the table. 
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Table 4-1 
PIP Switches 



Switch 



Section 



Explanation 



/A 

/B 

/C 

A> 

/E 

/F 
/G 



/I or no 

switch 

/K 



A 



/Mm 



4.2.2 

4.2.2 
4.2.2 

4.2.4 
4.2.6 

4.2.6 
4.2.2 
4.2.2 
4.2.12 

4.2.6 
4.2.1 



/N:n 



/O 



4.2.7 



4.2.10 



Copies file(s) in ASCII mode; ignores nulls and 

rubouts; converts to 7-bit ASCII; CTRL Z (32 octal) 
treated as logical end-of-f ile on input. 
Copies files in formatted binary mode. 

May be used in conjunction with another switch to 
cause only files with current date (as designated 
using the monitor DATE command) t<-> be included in 
the specified operation. 

Deletes file(s) from specified device. 

Lists the device directory including unused spaces 
and their sizes. An empty space on a cassette or 
magtape directory represents a deleted file. 
Sequence numbers are listed for cassettes. 

Prints a short directory (filenames only) of the 
specified device. 

Ignores any input errors which occur during a file 
transfer and continues copying. 

Copies file(s) in image mode (byte by byte). This 
is the default switch. 

Scans the specified device and types the absolute 
block numbers (in octal) of any bad blocks on the 
device. 

Lists the directory of the specified device, 
including the number of files, their dates, and 
the number of blocks used by each file. Sequence 
numbers are listed for cassettes. 

Used when I/O transfers involve either cassette or 
magtape, n represents the numeric position of the 
file to be accessed in relation to the physical 
position of the cassette or magtape on the drive. 
If n is positive, the tape spaces forward from its 
current position until either the filename or the 
nth file is found; if n is negative, the tape is 
rewound first, and then it spaces forward until 
either the filename or the nth file is found. If 
n is (or not indicated) the tape is rewound and 
searched for the filename. For wild card 
operations, specification of /M with a positive 
argument will prevent the tape from rewinding 
between each file involved in the operation. 

Used with /Z to specify the number of directory 
segments (n) to allocate to the directory. 

Bootstraps the specified device (DTO, RKn, RF, DPn, 
DSn, DXn only) . 
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Table 4-1 (Cont.) 
t>IP Switches 



Switch 


Section 


Explanation 


/Q 


4.2.2 


When used in conjunction with another PIP 
operation, causes PIP to type each filename which 
is eligible for a wild card operation and to ask 
for a confirmation of its inclusion in the 
operation. Typing a "Y" causes the named file to 
be included in the operation; typing anything 
else excludes the file. The command line is not 
processed until the user has confirmed each file 
in the operation. 


/R 


4.2.5 


Renames the specified file. 


/s 


4.2.8 


Compresses the files on the specified directory 
device so that free blocks are combined into one 
area. 


/T 


4.2.4 


Extends number of blocks allocated for a file. 


/u 


4.2.9 


Copies the bootstrap from the specified file into 
absolute blocks and 2 of the specified device. 


/v 


4.2.11 


Types the version number of the PIP program being 
used. 


Af 


4.2.6 


Includes the absolute starting block and any extra 
directory words in the directory listing for each 
file on the device (numbers in octal) . Used with 
/F, /L, or /E. 


A 


4.2.3 


Copies files individually (without concatenation) . 


A 


4.2.2 


Causes system files and .BAD files to be operated 
on by the command specified. Attempted 
modifications or deletions of .SYS or .BAD files 
without /Y are not done and cause the message ?N0 
SYS ACTION? to be printed. 


/2:n 


4.2.7 


Zeroes (initializes) the directory of the 
specified device; n is used to allocate extra 
words per directory entry. When used with /N, the 
number of directory segments for entries may be 
specified. When used with cassette, /Z writes a 
sentinel file at the beginning of the tape; with 
magtape, /Z writes a volume label followed by a 
dummy file followed by double tape marks 
indicating logical end-of-tape. 



4.2.1 Operations Involving Magtape or Cassette 

PIP operations involving cassette and magtape devices are handled 
somewhat differently than other RT-11 devices, because of the 
sequential nature of these devices. The last file on a cassette or 
magtape (the logical end-of-tape) is specially formatted so that it 
marks the end of current data and indicates where new data may begin 
(double end-of-file for magtape, sentinel file or physical end-of-tape 
for cassette). Therefore, operations which designate specific block 
lengths (such as /T and /N) are meaningless, and unused spaces on the 
tape (resulting from file deletions) cannot be filled. 
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PIP operations which are legal using cassette and magtape (including 
the bootable magtape on which the system may have been distributed) 
include the following: /A, /B, /D, /E, /F, /G, /I, /L, /M, /Q, /V, 
/W, /X, /Y, and /Z. Usually the device (CT or MT) is rewound each 
time an operation is performed. Since there is no inclusive directory 
at the beginning of the tape the only way to access a file is to 
search the tape from the beginning until it is found. However, the 
/M:n switch is available for situations where it is not necessary or 
desirable to rewind the tape before each operation. If the argument 
(n) is positive, the operation indicated will not rewind the tape 
first, but will space forward until it finds either the nth file, the 
filename indicated in the command line, or the logical end-of-tape, 
whichever occurs first. If the argument is negative, the cassette or 
magtape will be rewound first and then spaced forward until the file- 
name (or nth file, or logical end-of-tape) is found. Thus: 

/M:l means suppress rewind, begin operation at 

current position. 

/M:-l means rewind tape and access the first file 

on it. 

Remember that when /M:n is used, n is interpreted as an octal number. 
/Mln must be used if it is intended that n represent a decimal number. 

For example, assume the directory of a cassette on unit 1 is: 

17-JUL-74 

FILE .1 5-MAY-74 

FILE .2 5-MAY-74 

FILE .3 1 13-MAY-74 

FILE .4 1 28-JUN-74 

FILE .5 17-JUL-74 
5 FILES, 2 BLOCKS 
* 

and the last PIP operation involved FILE. 4, leaving the cassette 
positioned at the end of FILE. 4. To access FILE. 2, the next operation 
(for example, deleting FILE. 2) could use the /M construction: 

*CTl:DUH/M:-2/D 

In this case, the cassette rewinds first, then spaces forward from its 
current position to the second file in sequence and deletes it. (In a 
delete operation, the dummy filename is necessary; otherwise, a 
non-file structured delete is performed and the tape is zeroed. See 
Section 4.2.4) . 

Another useful application of the /M switch involves a case where a 
number of files are to be created on a magtape or cassette. Using the 
construction: 

*MT:*. */X=FILE. 1, FILE. 2. . . ,-'M : 1606 

prevents a rewind from occurring before each new file is created on 
the tape. Normal operation (when creating a new file on magtape or 
cassette) is to rewind, then search the tape for the logical end. If 
a file with the same name as the one being created is encountered, it 
is deleted and the new file is opened at the logical end of the tape. 
The /M:1000 command first causes the tape to space forward until it 
reaches the logical end-of-tape, (assuming less than 1000 (octal) 
files on the tape) , at which point the next file is entered, and so 
on. If the tape were already positioned at the end of the tape, an 
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/M:l would suffice to cause the new file to be written there. Note 
that creation of a new file with the /M switch can result in several 
files with the same name on the same tape; those files occurring 
before the tape position are not searched for duplication prior to the 
creation of the new file. 

RT-11 magtapes sometimes contain a dummy file at the beginning of the 
tape, which is written when the tape is initialized with the /Z 
switch. This file shows up in extended directories (/E) as an 
<UNUSED> entry in the first file position. Deleted files on magtape 
or cassette do not show up in /F or /L directory listings, but must 
always be considered when the /M:n switch is used. Care must always 
be taken to use a /E directory when counting file position prior to 
using that position as an /M:n argument; <UNUSED> files must be 
counted as files on the tape. 



For example: 



. R PIP 

*MT0.VE 

ll-SEP-74 

< UNUSED > 
ft . MAC 
B . MAC 

< UNUSED > 
D . MAC 
3 FILES, 5? 



9 
46 ll-SEP-74 
15 ll-SEP-74 

2 

2 ll-SEP-74 
BLOCKS 



Extended directory: shows 
absolute file positions. 



*MT0:/L 
ll-SEP-74 
A . MAC 
B . MAC 
D . MAC 



46 ll-SEP-74 

15 ll-SEP-74 

2 ll-SEP-74 



FILES, 57 BLOCKS 



Normal directory; does 
not accurately display 
file positions. 



If the user wished to access file A.MAC on the magtape in the example 
above, /M:-2 must be used (/M:-l would access the first empty file)., 
Likewise, B.MAC is accessed with /M:-3. Rewind can also be suppressed 
for cassette and magtape as input devices by specifying a very large 
number in conjunction with wild card transfers from magtape or 
cassette. 

**, *:-r<iT0 :*. *.-'M: 20SCVX 

This transfers all files from MTO: to DK: without rewinding between 
each file. The argument 2000 is an arbitrarily large number; any 
number larger than the actual number of files on the tape will 
suffice. 

The most common method for spacing to the end of the tape is: 

*DUMMV=MT0 : DUMMV/M : 208© 
?FIL NOT FND? 

where DUMMY is a file name which does not exist on the tape. Note 
that an error message is printed when the end of the tape is reached. 
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Directory listings of magtapes include the length of each file in 
256 (decimal) word blocks. In cassette directories, however, sequence 
numbers rather than block numbers are printed. Sequence numbers 
indicate the sequential ordering of a file in cases where it has been 
continued on more than one cassette. In the example cassette 
directory listing (at the beginning of this section) , the numbers in 
the middle column represent sequence numbers; both PILE. 3 and FILE. 4 
are the second segments of continued files. All files on cassette are 
initially assigned a sequence number of (meaning this is the first 
segment of the cassette file, not that the file has no length) . The 
sequence number is automatically updated whenever the file must be con- 
tinued as a result of a full cassette. 

During I/O transfer operations involving cassette, if the cassette is 
full before the transfer has finished, the message: 

CTn: PUSH REWIND OR MOUNT NEW VOLUME 

is printed; n represents the number of the drive (0 or 1) on which 
the current cassette is mounted. If the cassette rewind button is 
subsequently pushed, an error message is typed (IN or OUT ERR) and the 
tape is rewound. 

To continue an output operation, mount a new cassette (which has been 
properly formatted as described in Section 4.2.7) on the same drive. 
The new cassette is rewound automatically and a file is opened on it 
under the same name and extension; the sequence number in its 
directory is updated to reflect the continuation, and the transfer 
continues. 

If the message occurs during an input operation, mount the cassette 
containing the continued portion of the file on the drive; the 
cassette is rewound first. PIP then looks for a file with the same 
name and extension and the proper sequence number and continues the 
input operation. The message is repeated if the next segment is not 
found . 

For example t 

*CT0:FILE. RGfl=DTl : RSC. MfiC, DK : BFILOR. MflC/fl 
CT9 : PUSH REWIND OR MOUNT NEW VOLUME 

This copies in ASCII mode the file ASC.MAC from DECtape 1 and 
BALOR.MAC from device DK and combines them under the name FILE.AGA on 
CTO. The cassette runs out of room and requests that a new one be 
mounted. The operation continues automatically when the second 
cassette has been mounted. 

A directory of the second cassette in the above operation is next 
requested; note that the sequence number of FILE.AGA is 1, signifying 
it is the second part of a continued file. 

*CT0:/L 

23-MAY-74 

TRA .BIN 16-FEB-74 

FILE .AGA 1 23-MAY-74 

2 FILES, I BLOCKS 

* 

(The number of blocks in a cassette directory simply represents the 
total of sequence numbers in the directory.) 

Any cassette mounted in response to a continuation message MUST have 
been previously initialized at some time as described in Section 
4.2.7. 

4_7 January 1976 



Peripheral Interchange Program 

If a full cassette is mounted or an attempt is made to access some 
file on it that does not exist, the continuation message recurs. 
The operation may be continued by mounting another cassette. 

Note that if an attempt is made to access a file which has a non-zero 
sequence number (during some operation which is not a continuation of 
an operation), the file will not be found. 

To copy multiple files to a cassette using a wild card command, use 
the following: 

*CTn:*.*=DEV:*. */X/M:l (rewind is inhibited) 

Continue to mount new cassettes in response to the PUSH REWIND OR 
MOUNT NEW VOLUME message. Do not abort the process at any time (using 
two CTRL Cs) since continuation files may not be completed and no sen- 
tinel file will be written on the cassette. 

To read multiple files from a. cassette, use the following: 

*DEV:*.*=CTn:*.*/X/M:1000 (rewind is inhibited) 

Whenever a continued volume is detected, the PUSH REWIND OR MOUNT NEW 
VOLUME message will appear, until the entire file has been copied (as- 
suming that each sequential cassette is mounted in response to each oc- 
currence of the message) . Whenever PIP has copied the final section 
of a continued file, it will return to command level. To copy the 
remaining files on that cassette, reissue the command: 

*DEV:*.*=CTn:*.*/X/M:100 

Repeat the process as often as necessary to copy all files. Do not 
abort the process at any time (using two CTRL Cs) since continuation 
files may not be completed. 

If the end of a tape is reached during a magtape I/O operation, an IN 
or OUT ERR message is printed. In the case of an output operation, 
the magtape backspaces and deletes the partial file by writing logical 
end of tape over the file's header label. The operation must then be 
repeated using another magtape. 

If CTRL C is typed during any output operation to cassette or magtape, 
an end-of-tape or sentinel file is not written on the tape first. 
Consequently, no future enters may occur to the tape unless one of two 
recovery procedures is followed: 

1. Transfer all good files from the bad tape to another tape and 
zero the bad tape in the following manner: 

*devl:*.*/X-devO:filel,file2,...filen/M:1000 

*devO:/Z 

devO:/Z APE YOU SURE ? 

This causes a logical end-of-tape to be written onto the bad 
tape and makes it again available for use. 
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2. Determine the sequential number of the file which was 
interrupted and use the /M construction to enter a 
replacement file (either a new file or a dummy file) . 
Assuming the bad file is the 4th file on the tape, use a 
command line of this construction: 

*devO:file.new=file.dum/M:-4 

A logical end-of-tape now exists on the tape, making it 
available for use. 

Since magtapes and cassettes are not random access devices, each unit 
can have only one file accessed at a time. Avoid PIP command strings 
which specify the same unit number for both input and output, since a 
loss of information can occur. For example: 

*CT0:FILE1 .MAOCT0: FIL£1 .MAC 
?FIL NOT FND? 

The result of this operation is to delete FILE1.MAC before the error 
message is printed, and the tape label structure may be destroyed. 

Recovery procedures for errors caused by bad tapes are described in 
RT-11 Software Support Manual. 
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4.2.2 Copy Operations 

A command line without a switch causes files to be copied onto the 
destination device in image mode (byte by byte) . This operation is 
used to transfer memory image (save format) files and any files other 
than ASCII or formatted binary. For example: 

*FlBC<XVZ Makes a copy of the file named XYZ on 

device DK and assigns the name ABC. 
(Both files exist on device DK following 
the operation) . 

*SV:BfiCK. BIN=PR./I Copies a tape from the papertape reader 

to the system device in image mode and 
assigns it the name BACK. BIN. 

The /A switch is used to copy file(s) in ASCII mode as follows: 

*DT1 .FKF2/FI Copies F2 from device DK onto device DTI 

in ASCII mode and assigns the name Fl. 

Nulls and rubouts are ignored in an ASCII mode file transfer. CTRL Z 
(32 octal) is treated as logical end-of-file if encountered in the 
input file. 

The /B switch is used to transfer formatted binary files. The 

formatted binary copy switch should be used for .OBJ files produced by 

the assembler or FORTRAN and for .LDA files produced by the Linker. 
For example: 

*0K : FILE. OBJ <PR : /B Transfers a formatted binary file from 

the papertape reader to device DK and 
assigns the name FILE. OB J. 

When performing formatted binary transfers, PIP verifies checksums and 
prints the message ?CHK SUM? if a checksum error occurs. 

If neither /A nor /B is used in a copy operation that involves a paper 
tape device, the size of the output file in the operation depends upon 
the memory size of the system. The transfer mode defaults to image 
mode and PIP attempts to do a single read to fill its input buffer. 
When a read from the paper tape reader encounters end-of-tape, no count 
of words transferred can be returned; PIP assumes its input buffer is 
full and copies it to the output device. The output file size thus 
depends upon the input buffer size, which is determined by the memory 
size of the system. The output file will have several blocks of zeroes 
after the end of the paper tape image. If copying to the punch, large 
amounts of blank tape will be punched after the input tape image is 
output. The extra length is harmless, but can be avoided by use of /A 
or /B. Image mode files (for example, .SAV files) cannot reliably be 
transferred to or from paper tape. 

To combine more than one file into a single file, use the following 
format : 

*DK:Rfl<DTl:BB, CC, C'D/I 

Transfers files BB, CC and DD to device 
DK as one file and assigns this file the 
name AA. 
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*DT3 :MERGE = DT2:FI|.E2, FILEK/fl 

Merges ASCII files FILE2 and FILE3 on 
DT2 into one ASCII file named MERGE on 
device DT3. 

Errors which occur during the copy operation (such as a parity error) 
cause PIP to output an error message and return for another command 
string. 

The /G switch is used to copy files but ignore all input errors. For 
example : 

*RBC<DT1: TOP/G Copies file TOP in image mode from 

device DTI to device DK and assigns the 
name ABC. Any errors during the copy 
operation are ignored. 
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+ DT2 : COHB'CDTl : F'l, F 2,-'fl,'G 

Copies files Fl and F2 in ASCII mode 
from device DTI to device DT2 as one 
file with the name COMB. Ignores input 
errors . 

The wild card construction may be used for input file specifications 
during copy operations. Be sure to use the /Y switch if system files 
(.SYS) are to be copied. For example: 

*DT1 S PROG :l.<#. MAC Copies, in image mode, all files with a 

.MAC extension from device DK to device 
DTI and combines them under the name 
PR0G1. 

**.*=DT3!#.*/G/Y/X Copies to device DK, in image mode, all 

files (including .SYS files) from device 
DT3; ignores any input errors. 

If only files with the current date are to be copied (using the wild 
card construction) , the /C switch must also be used in the command 
line. For example: 

*DT2:NN3=ITEM1. */C, ITEM2VR 

Copies, in ASCII mode, all files having 
the filename ITEMl and the current date, 
(the date entered using the monitor DATE 
command) and copies ITEM2 (regardless of 
its date) from device DK to device DT2 
and combines them under the name NN3. 

*DT3 :*.*=*. +/C/X Copies all files with the current date 

from DK to DT3. Note that commands of 
this nature are an efficient way to 
backup all new files after a session at 
the computer. 

The /Q switch is used in conjunction with another PIP operation and 
the wild card construction to list all files and allow the user the 
opportunity to confirm individually which of these files should be 
processed during the wild card expansion. Typing a "Y" causes the 
named file to be processed; typing anything else excludes the file. 
For example: 

**.OBJ<»TJ. :*,GBJ/U/X 

FIRST . GBJ'i'Y Copies the files FIRST. OBJ and 

GETR . OBJ? CARJ.OBJ to the disk in 

BORD .OBJ? image mode from DEC tape 1 

GAR J . OBJ?Y and ignores the others. 

The file allocation scheme for RT-11 normally allows half the entire 
largest available space or the second largest space, or a maximum size 

(a constant which may be patched in the RT-11 monitor; see the RT-11 
System Generation Manual) , whichever is largest, for a new file. The 
user can, using the In] construction explained in Chapter 2, force 
RT-11 to allow the entire largest possible space by setting n=177777. 
If n is set equal to any other value (other than which is default 
and gives the normal alloc^t-ion described first above), that size will 
be allocated for the fi" 
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Therefore, assume that the directory for a given device shows a free 
area of 200 blocks and that PIP returns an ?OUT ER? message when a 
transfer is attempted to that device with a file which is longer than 
100 blocks but less than 20 blocks. Transfers in this situation can 
be accomplished in either of two ways: 

1. Use the [n] construction on the output file to specify the 
desired length (refer to Chapter 2, Section 2.5 for an 
explanation of the [n] construction) . 

2. Use the /X switch during the transfer to force PIP to 
allocate the correct number of blocks for the output file. 
This procedure will operate correctly if the input device is 
DECtape or disk. 

For example, assume that file A is 150 blocks long and that a 
directory listing shows that there is a 200 block <unused> space on 

DTI: 

. R PIP 

*DTl:R=fi 

?0UT ER? File longer than 100 blocks. 

*DTl:flC150]=fl 
°* Either command causes a correct 

*DTl:fl=fl/X transfer. 



4.2.3 Multiple Copy Operations 

The /X switch allows the transfer of several files at a time onto the 
destination device as individual files. The /A, /G, /C, /Q, /B and /Y 
switches can be used with /X. If /X is not indicated, all output files 
but the first will be ignored. 

Examples : 

*f:i:i...e :i. ,- file 2 y file ;s<dt.i. t f;i:lea ? f:i:leb > filec/x 

Copies, in image mode, FILEA, FILEB and 
FILEC from device DTI to device DK as 
separate files called FILE1, FILE2 and 
FILE3, respectively. 

*DT2:F1. *=F2. */X Copies, in image mode, all files named 

?N0 5VS ACTION? F2 (except files with .SYS or .BAD 

extensions) from device DK to device 
DT2. Each file is assigned the filename 
Fl but retains its original extension. 



* 



*DT1!*.*=-~»T2:*.*/X Copies, in image mode, all files on 
?N0 SYS ACTION? device DT2 to device DTI (except files 

with .SYS or .BAD extensions); the files 
are copied separately and retain the 
same names and extensions. 

*DT1:FILE1, FILE2<FILER. *,-'fl/G/X 

This command line assumes there are two 
files with the filename FILEA (and any 
extension excluding .SYS or .BAD 
extensions) and copies these files in 
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ASCII mode to device DTI. The files are 
transferred in the order they are found 
in the directory; the first file found 
is copied and assigned the name FILEl, 
and the second is assigned FILE2. If 
there is a third, it is ignored and a 
fourth causes an ?OUT FIL? error. 

+ DT0 :*. SVS = *. SVS/X/V 

Copies all system files from device DK 
to device DTO. 

File transfers performed via normal operations place the new file in 
the largest available area on the disk. The /X switch, however, 
places the copied files in the first free place large enough to 
accommodate it. Therefore, the /X switch should be used whenever 
possible (i.e., when no concatenation is desired) as an aid to 
reducing disk fragmentation. 

+ fi=B 
and 

*fi=B/X 

perform the same operation; however, using the second construction 
whenever possible increases the system disk-usage efficiency. 

For example, assume the directory of DTI is: 

9-I1RV-74 

MONITR. SVS 32 5-MRV-74 

<:: UNUSED > 2 

PR . SVS 2 5-MRV-74 

<:: UNUSED > 528 

2 FILES, 34 BLOCKS 

530 FREE BLOCKS 

To copy the file PP. SYS (2 blocks long) from DK to DTI, the command: 

*DT1:PP. SVS=PP. SVS/V 
can be entered, and the new directory is: 

9-MRV-74 
MONITR. SVS 32 5-MRV-74 

< UNUSED > 2 

PR . SVS 2 5-MRV-74 
PP . SVS 2 9-MRV-74 

< UNUSED > 526 

3 FILES, 36 BLOCKS 
528 FREE BLOCKS 

If the command: 

*DT1:PP. SVS=PP. SVS/V/X 

had been entered, the new directory would appear: 
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9-MRV-74 

MONITR. 5VS 22 5-MRV-74 

PP • SV5 2 9-MRV-74 

PR . SV5 2 5-MRV-74 

< UNUSED > 528 

3 FILES, 36 BLOCKS 

528 FREE BLOCKS 

4.2.4 The Extend and Delete Operations 

The /T switch is used to increase the number of blocks allocated for 
the specified file. The file associated with the /T switch must be 
followed by a numeric argument of the form [n] where n is a decimal 
number indicating the number of blocks to be allocated to the file at 
the completion of the extend operation. 

The format of the /T switch isi 

dev: f ilnam.ext [n] -/T 

A file can be extended in this manner only if it is followed by an 
unused area of sufficient size (on whichever device it is located) to 
accommodate the additional length of the extended file. It may be 
necessary to create this space by moving other files on the device 
using the /X switch. 

Specifying the /T switch in conjunction with a file that does not 
currently exist creates a file of the designated length. 

Error messages are printed if the /T command makes the specified file 
smaller (?EXT NEG?) or if there is insufficient space following the 
file (7R00M?). y 

Examples : 

*RBCC200 3=/T Assigns 200 blocks to file ABC on device 

DK. 

*DT1:,\'VZ[ 180 K/T Assigns 100 blocks to the file named XYZ 

on device DTI. 

The /D switch is used to delete one or more files from the specified 
device. The wild card character (*) can be used in conjunction with 
this command. 

Only six files can be specified in a delete operation if each file to 
be deleted is individually named (i.e., if the wild card character is 
not used) . 

A cassette or magtape may be initialized by indicating the /D switch 
and omitting any filenames. For example: 

*MT:/D 
+ CT :/D 

Both devices are zeroed. This is not the case with the other RT-11 
devices, where omission of a filename causes no action to occur. 
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When a file is deleted on block-replaceable devices, the information 
is not destroyed. The file name is merely removed from the directory. 
If a file has been deleted but not overwritten, it can be recovered 
with the /T switch by specifying a command of the form: 

filena.ext[nJ=/T 

where filena.ext is the name desired and n is the length of the 
deleted file. For example: 

*DT1 :/E 

4-JUN-74 

fl . MAC 18 3-JUN-74 

B . MAC 1? 3-JUN-74 

C . MRC 19 3-JUN-74 

< UNUSED > 519 

3 FILES, 54 BLOCKS 

510 FREE BLOCKS 



+ DT1 :B. MRC, 


•'D 




*DT1 :,'E 






4-JUN-74 






fl . MAC 


18 


2-JUN-74 


< UNUSED > 


1? 




C . MRC 


19 


3-JUN-74 


< UNUSED > 


510 





2 FILES, 37 BLOCKS 
527 FREE BL0CK5 

File B.MAC could now be recovered by: 
*DT1:B. MRCt 1?]=/! 

The /T switch looks for the first unused area large enough to 
accommodate the requested file length. If the file to be recovered is 
in the first area large enough to accommodate the size specified, the 
preceding command is sufficient. If not, all larger unused spaces 
preceding the desired file must be given dummy names before the 
recovery can be made. 

For instance, assume the previous example with the exception that 
A.MAC has a 33 block unused file before it, so that the directory 
looks like: 

*DT1.VE 

4-JUN-74 

< UNUSED > 33 

Fl . MRC IB 3-JUN-74 

: UNUSED > 17 

C . MRC 19 3-JUN-74 

<C UNUSED > 477 

2 FILES, 27 BLOCKS 

527 FREE BLOCKS 

A recovery of B.MAC would require: 

*DTl.DLIMt1Y[33 3 = /T 
*DT1 :B. MFICC17 3= f -'T 
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If the 33 block unused area was not named prior to B.MAC, the first 17 
blocks of the 33 block area would become B.MAC. Note that magtape and 
cassette files cannot be recovered once deleted. 

Examples : 

*FILE1. SflV/D Deletes PILE1.SAV from device DK. 

*DT1:*. */D Deletes all files from device DTI except 

those with a .SYS or .BAD extension. If 
there is a file with a .SYS or .BAD 
extension, the message ?N0 SYS ACTION? 
is printed to remind the user that these 
files have not been deleted. 

**. MflCVD Deletes all files with a .MAC extension 

from device DK. 

*DT1 : Bl, C-T2 : Rl, DT3 : flfl/D 

Deletes the files specified from the 
associated devices. 

*RK:l. t*,*/l.i/Y Deletes all files from device RK1. 



4.2.5 The Rename Operation 

The /R switch is used (in a manner similar to the multiple copy 
command described in Section 4.2.3) to rename a file given as input 
with the associated name given in the output specification. There 
must be an equal number of input and output files and they must reside 
on the same device, or an error message will be printed. The /Y 
switch must be used in conjunction with /R if .SYS files are to be 
renamed . 

The Rename command is particularly useful when a file on disk or 
DECtape contains bad blocks. By renaming the file with a .BAD 
extension, the file permanently resides in that area of the device so 
that no other attempts to use the bad area will occur. Once a file is 
given a .BAD extension it cannot be moved during a compress operation. 
.BAD files are not renamed in wild card operations unless /Y is used. 



Examples : 

*DT1 :F1, XKDT1.-F0, XQ/R Renames FO to Fl and XO to XI on 

device DTI. 

*FILE1. *<FILE2. */R Renames all files on device DK with 

the name FILE2 (except files with 
.SYS or .BAD extension) to FILEl, 
retaining the original extensions. 

/R cannot be used with magtape or cassette. 

4.2.6 Directory List Operations 

The /L switch lists the directory of the specified device. The 
listing contains the current date, all files with their associated 
creation dates, total free blocks on the device if disk or DECtape, 
the number of files listed, and number of blocks used by the files 
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(sequence number for cassette). File lengths, number of blocks and 
number of files are indicated as decimal values. If no output device 
is specified, the directory is output to the terminal (TT:). 



Examples : 



22 
2 
2 

15 



*DT1:/L 

l-RUG-74 
MONITR. SVS 
PP . SVS 
PR .SVS 
F2 . REL 
MERGE 2 

COMB 2 

6 FILES, 55 BLOCKS 

509 FREE BLOCKS 

*DIRECT^DT3;/L 



5-MRV-74 
9-MRV-74 
5-MRV-74 



Outputs complete directory of 
device DTI to the terminal. 



Outputs complete directory of 
device DT3 to a file, DIRECT, 
on the device DK. 



+ *. MRCv'L 




l-flUG-74 




VTMflC . MAC 7 22-JUL- 


74 


FILE2 . MflC 1 




2 FILES, 8 BLOCKS 




3728 FREE BLOCKS 
* 




*CT1:/L 




10-SEP-74 




PflTl . FOR 6 10-SEP- 


-74 


PftT2 . FOR 10-SEP- 


■74 


IMUL . OBJ 10-SEP- 


-74 


SQRT . FTN 10-SEP- 


-74 


4 FILES, BLOCKS 





Lists on the terminal a 
directory of files on device 
DK with the extension .MAC. 



Lists all files on cassette 
drive 1. For cassette only, 
the third column represents 
the sequence number. In 
this example, the first seg- 
ment of each file is on this 
cassette. (See Section 
4.2.1.) 



The /E switch lists the entire directory including the unused areas 
and their sizes in blocks (decimal) ; an empty space appears in 
cassette and magtape directories to designate a deleted file. 



Examples : 



*/E 

9 ■■SEP 
BATCH 
CHESS 

rati 



-74 
.HI...P 
»SAU 
.FOR 



IRABSO.MAC 



2 2 3 -AUG- 7 4 
20 23- AUG -74 
10 2 3- AUG- 7 4 

8 23 -AUG- 7 4 



Outputs to the terminal a 
complete directory of the 
device DK including the size 
of unused areas. 
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< UNUSED > 
TRIG .OBJ 



6 •■•SEP ■■■■? 4 



SIP .OBJ 
BAG .OBJ 
•■•:: UNUSED > 



■74 
■74 



LIBR1 .OBJ 137 6 -SEP -■74 
DIRECT :l. 9 •■••SEP -7 4 

< UNUSED > 230 
254 FILES , 4280 BLOCKS 
498 FREE BLOCKS 



*LP:=CT1:/E 

1 l»SEP»7<i 

A .MAC U-8EP-74 

A .MAC U»SEP»7« 

8 ,MAC U«SEP^7« 

3 FILES, BLOCKS 



Outputs to the line printer 
a complete directory of 



cassette drive 1. 
represent segment numbers. 



The /F switch lists 
associated dates. 



0's 



only filenames, omitting the file lengths and 



Examples i 



+ DT0.VF 
TRACE . MAC 
CARGO . REL 
BMAP . OBJ 
flAR 



Outputs a filename directory 
of the device DTO to the 
terminal. 



*LP:=CT1:/F 



.MAC 
.MAC 
.MAC 



Outputs a filename directory 
of the device CT1 to the line 
printer. 



The /L, /E and /F commands have no effect on the files of the speci- 
fied device. If the /W switch is used in conjunction with the /L or 
/E switches, the absolute starting block of the file and extra words 
(in octal) will be included in the listing (for all but cassette and 
magtape). For example: 



*RK1 S/I.../W 










10 -■SEP-- 7 4 










DSORT .OBJ :l. 


1.0-SEI 


:'.... 7 4 


.1. 6 





MAIN .OBJ :l. 


1. 0-SEI 


:■.... 7 4 


17 





BASICR.OBJ 11 


1.0-SEI 


:•.... 7 4 


20 





0TSM2 .OBJ 3 


1.0-SEI 


:•.... 7 4 


33 






The first three columns indicate the filename and extension, block 
length, and date. The fourth column shows the absolute starting block 
(in octal) , and the fifth column shows the contents of each extra word 
per directory entry (in octal). (This is allocated using the /Z:n 
switch; see Section 4.2.7.) 
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Using the /L, /E, or /F switch in conjunction with a device and 
filename causes the filename, and optionally the date and file length, 
to be output rather than a directory of the entire device. For 
example : 

*F1. SfiVVL 

causes : 

4-JUN-74 
Fl . SflV 18 4-JUN-74 
3710 FREE BLOCKS 
* 

to be output, providing the file existB on device DK. 

Directories are made up of segments which are two blocks long. Full 
directory listings with multiple segments contain blank lines as 
segment boundaries. 

4.2.7 The Directory Initialization Operation 

The /Z switch clears and initializes the directory of an RT-11 direc- 
tory-structured device and writes logical end-of-file to a cassette 
or magtape device. The /Z operation must always be the first opera- 
tion performed on a new (that is, previously unused) device. The 
form of the switch is: 

/Z:n 

where n is an optional octal number to increase the size of each direc- 
tory entry on a directory-structured device. If n is not specified, 
each entry is 7 words long (for filename and file length information) 
and 70 entries can be made in a directory segment. When extra words 
are allocated, the number of entries per directory segment decreases., The 
formula for determining the number of entries per directory segment is: 

507/((# of extra words) +7) 

For example, if the switch /Z:l is used, 63 entries can be made per 
segment. 

More information concerning the format of directory entries is supplied 
in Chapter 3 of the RT-11 Software Support Manual . 

When /Z is used, PIP responds as follows: 

device/Z ARE YOU SURE ? 

For example: 

*DTl:/2 

DT1:/Z ARE VOU SURE ? 

Answer Y and a carriage return to perform the initialization. An 
answer beginning with a character other than Y is considered to be no. 

Example : 

*DT1:/Z 

DT1:/Z RRE VOU SURE ?V<CR> 

* Zeroes the directory on device DTI and 

allocates no extra words for the 

directory. 
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The /N switch is used with /Z to specify the number of directory seg- 
ments for entries in the directory. The form of the switch is: 

/N:n 

where n is an octal number less than or equal to 37. Initially RT-11 
allocates four directory segments, each two blocks (512 words) long. 
Refer to Chapter 3 of the RT-11 Software Support Manual for more in- 
formation. 

Example: 

*RK:I. 1/Z12/H16 Zeroes the directory on device RKl, al- 

locates two extra words per directory 
entry and allocates six directory seg- 
ments . 

4.2.8 The Compress Operation 

The /S switch is used to compress the directory and files on the speci- 
fied device, condensing all the free (unused) blocks into one area. 
Input errors are reported on the console terminal unless the /G switch 
is used; output errors are always reported. In either case, the com- 
press continues. /S can also be used to copy DECtapes and disks. 
When DT, DP, or RK devices are copied, /S serves to both initialize 
the volume and to copy directory and files. When DX disks are copied, 
however, the output diskette must first be initialized using /Z to 
write the appropriate volume identification. (It is important to 
note that the /S switch destroys any previous directory on the output 
device. The new directory on the output device has the same number 
of segments as the directory on the input device.) /S does not copy 
the bootstrap onto the volume. 

To increase the number of directory blocks in a two-volume compress 
(that is, from one volume to another rather than from one volume to 
itself) , use the /N:n switch in conjunction with the /S switch (any 
attempts to decrease the directory size are ignored) . 

/S does not move files with the .BAD extension. This feature provides 
protection against reusing bad blocks which may occur on a disk. 
Files containing bad blocks can be renamed with the .BAD extension and 
are then left in place when a /S is executed. 

If a compress operation is performed on the system device, the 
message: 

7REB00T? 

is printed to indicate that it may be necessary to reboot the system. 
If .SYS files were not moved during the compress operation, it is not 
necessary to reboot the system. 

NOTE 

Rebooting the system in response to the 
7REBOOT? warning message should ONLY be 
done AFTER the operation which generated 
the message is complete. ?REBOOT? does 
not signify that the system should be 



4-19 January 1976 



Peripheral Interchange Program 



rebooted immediately; the user should 
wait for the "*" signifying that PIP is 
ready for another command before 
rebooting. 



If the command attempts to compress a large device to a smaller one, 
an error results and the directory of the smaller device is zeroed. 
If a device is being compressed in place, input and output errors are 
reported on the terminal and the operation continues to completion. 



Examples: 



*SV:/S 
''REBOOT? 



Compresses the files on the system 
device SY: 



*DT1 :R<DT2:, 



Transfers and compresses the files from 
device DT2 to device DTI. Device DT2 is 
not changed. The filename A is a dummy 
specification required by the Command 
String Interpreter. 



/S cannot be used when a foreground job is present; 
error message results if this is attempted. 



a ?FG PRESENT? 



4.2.9 The Bootstrap Copy Operation 

The bootstrap copy switch (/U) copies the bootstrap portion of the 
specified file into absolute blocks and 2 of the specified device. 



Examples : 



*DK:FKDK :MONITR. SVS/U 

V/rites the bootstrap file MONITR.SYS in 
blocks and 2 of the device DK. A is a 
dummy filename. 

* d t ! m n i t r . s y 8 / x / y -■ r k t d t m n s j . s y s 
*dt:a==rk;i:itmnsj.sys/u 

Writes the Single-Job DECtape Monitor 
to device DTO and then writes the boot- 
strap into blocks and 2 (the bootstrap 
is written from disk rather than DECtape 
because disk is faster) . 

4.2.10 The Boot Operation 

The boot switch reboots the system, reinitializing monitor tables and 
returning the system to the monitor level. The boot switch performs 
the same operation as a hardware bootstrap. 



Example : 



*dk:/o 



Reboots the device DK. 
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If a boot switch is specified on an illegal device, the message: 

?BAD BOOT? 

is printed. Legal devices are DTO, RK0-RK7 , RF , SY, DK, DP0-DP7, 
DXO-DXl, and DS0-DS7. Note that /O is illegal if a foreground job 
is present; the ?FG PRESENT? error message results. The user must 
abort the foreground job and unload it before using /0. 



4.2.11 The Version Switch 

The Version switch (/V) outputs a version number message (representing 
the version of PIP in use) to the terminal using the form: 

PIP V02-XX 

The rest of the command line, if any, is ignored. 



4.2.12 Bad Block Scan (/K) 

The bad block switch (/K) scans the specified device and types the 
absolute block numbers of those blocks on the device which return 
hardware errors. The block numbers typed are octal; the first block 
on a device is 0(8). Note that if no errors occur, nothing will be 
output. A complete scan of a disk pack takes several minutes. 



Example : 






KRK2S/K 
BLOCK 




*rk:/k 


4.2.12.1 


Recover 



4 



PAD 



Scan disk drive 2 for bad blocks, 



Scan drive 0. No blocks are bad. 



As a disk ages, the recording surface wears. Eventually unrecoverable 
I/O errors occur during attempts to read or write a bad disk block. 
PIP protects against usage of bad disk areas by ignoring files with a 
.BAD extension (unless the /Y switch is used) . Once a bad block is 
uncovered in an I/O operation, it can be located using the /K switch 
and a .BAD file can be created which encompasses the bad block. 



When a hardware I/O error is detected, the recovery procedure 
follows : 



is as 



1. Use the PIP /K switch to scan the device and print on the 
terminal the absolute block numbers (in octal) of the bad 
blocks. For example: 



R PIP 
*RK1 : /K 
BLOCK ??\ 
* 



IS BAD 
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2. Obtain an extended directory with the /W switch, showing the 
starting block numbers of all the files on the disk. 

3. If a bad block occurs in a file with valuable information, 
copy the file to another file using the /G switch. In most 
cases, only 1 bit (character) of the file is affected. 

4. If the file is small, it can then be renamed with a .BAD 
extension to prevent further use of that disk area. 

5. If the file is large or the bad block occurs in an empty 
area, a 1-block .BAD file can be created using the /T switch 
as follows: 

a. Delete the bad file (if any) . 

b. If the bad block is at block n of the free area, create a 
file of length n-1 with the /T switch. Remember that 
there must be no spaces larger than n-1 blocks before the 
desired one (refer to Section 4.2.4) . Also note that the 
block numbers printed in the /K and /W operations are 
octal, while the argument to the /T operation is decimal. 

c. Create a 1-block .bad file with the /T switch to cover 
the bad block. 

d. Delete any temporary files created during the operation. 
For example , assume the extended directory is : 



NEwSKC.BAT 8 il-SEP-74 6203 

RTTEMP.BAT 2? Il-SEP-74 6213 

PIP .MAC 150 12-SEP-74 6246 

« UNUSED * 154 

VERIFY. SAV 3 6726 

* UNUSED > 3(10 

PIP .OBJ 15 12-SEP-74 7«05 

MKPIP .CTt J 12-SEP-74 7424 

MKV2RK.CTL 4 12-SEP-74 7425 

VTLIB ,06J 10 12-SEP-74 7431 

« UNUSED * 150 

A 4 12-SEP-74 7671 

PIP ,LST 300 3-SEP-74 7675 Block 7723 (octal) of 

• PIP.LST is bad. 

■ 

and a bad block is detected at block 7723 (octal) of the file PIP.LST. 
To recover, make a copy, ignoring the error, and delete the bad file: 

*RK1:PIPR. LST=RK1:PIP. LST/G 
*RK1:PIP. LSTVD 

The directory now reads : 



NEW8RC.BAT 8 ll-SEP-74 6203 

RTTEMP.BAT 27 ll-SEP-74 6213 

PIP .MAC 150 12-SEP-74 6246 
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< UNUSED > 


154 






VERIFY. SAV 


3 




6726 


PIPA ,L8T 


300 


18-SEP-74 


6731 


PIP .OBJ 


15 


12-SEP-74 


7405 


MKPIP ,CTU 


1 


12-SEP-74 


7424 


MKV2RK.CTL 


4 


12-SEP-74 


7425 


VTLIB .OBJ 


10 


12-SEP-74 


7431 


* UNUSED > 


150 






A 


4 


12-SEP-74 


7671 



An unused area following A contains block 7723 (octal) , which 
is bad. Continuing in PIP: 

*RK1 : TEMP. @62C 154 3=/T 
*RK1 : TEMP. 663C 15@ 3=/T 
*RK1:TEMP. 004[ 22 D=/T 

This fills the unused areas with temporary files. Specifying 
TEMP. 004 with a length of 22 blocks makes the file just long 
enough to precede the bad block (i.e., 7675 (octal) and 22 
(decimal) equal 7723, which would be the starting block 
number of the next file created) . The directory now contains : 



NEWSRC 


.BAT 


8 


ll-SEP-74 


6203 


RTTEMP 


.BAT 


27 


ll-SEP-74 


6213 


PIP 


.MAC 


150 


12-SEP-74 


6246 


TEMP 


.002 


154 


18-SEP-74 


6474 


VERIFY 


.SAV 


3 




6726 


PIPA 


.LST 


300 


18-SEP-74 


6731 


PIP 


.OBJ 


15 


12-SEP-74 


7405 


MKPIP 


,CTL 


1 


12-SEP-74 


7424 


MKV2RK 


.CTL 


4 


12-8EP-74 


7425 


VTLIB 


.OBJ 


10 


12-SEP-74 


7431 


TEMP 


.003 


150 


18-SEP-74 


7443 


A 




4 


12-SEP-74 


7671 


TEMP 


.004 


22 


18-SEP-74 


7675 



Continuing with PIP: 

*RK1:FILE. BflDC i D=/V/T 
The directory now contains: 



Create a bad file, 



NEWSRC 


.BAT 


e 


ll-SEP-74 


6203 


RTTEMp 


.BAT 


27 


ll-SEP-74 


6213 


PIP 


.MAC 


150 


12-SEP-74 


6246 


TEMP 


.002 


154 


18-SEP-74 


6474 


VERIFY 


.SAV 


3 




6726 


PIPA 


.LST 


300 


18-SEP-74 


6731 


PIP 


.OBJ 


15 


12-SEP-74 


7405 


MKPIP 


.CTL 


1 


12-SEP-74 


7424 


MKV2RK 


.CTL 


4 


12-SEP-74 


7425 


VTLIB 


.OBJ 


10 


12-SEP-74 


7431 


TEMP 


.003 


150 


18-SEP-74 


7443 


A 




4 


12-SEP-74 


7671 
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TEMP ,004 22 J8-SEP-74 7675 
FILE .BAD 1 18-SEP-74 7723 



Bad block is here. 



Next delete all temporary files and rename PIPA.LST to 
PIP.LST. The final directory now contains: 



NEWSR 
PTTEM 
PIP 

< UNU 
VERIF 
PIP 
PIP 
MKPIP 
MKV2R 
VTLIB 

< UNU 
A 

< UNU 
FILE 



C.BAT 

P. BAT 

.MAC 

SED > 

Y.SAV 

.LST 

.OBJ 

.CTL 

K.CTL 

.OBJ 

SED > 

SED > 
.BAD 



e 

27 
150 

154 
3 

300 

15 

1 

4 

10 

150 

4 

22 

1 



11- 
11- 
12- 



18- 
12- 
12- 
12- 
12- 



SEP-74 
SEP-74 
SEP-74 



SEP-74 
SEP-74 
SEP-74 
SEP-74 
SEP-74 



12-SEP-74 



6203 
6213 
6246 

6726 
6731 

7405 
7424 
7425 
7431 

7671 



18-SEP-74 7723 



Disks with many bad blocks can often be reused by 
reformatting them. First copy all desired files, since 
reformatting destroys all information contained on a volume. 

4.3 PIP ERROR MESSAGES 

The following error messages are output on the terminal when PIP is 
used incorrectly: 



Errors 

?BAD BOOT? 

?BOOT COPY? 
?CHK SUM? 
?COR OVR? 

?DEV FUL? 
?ER RD DIR? 

?ER WR DIR? 

?EXT NEG? 
?FG PRESENT? 

?FIL NOT FND? 



Meaning 

A boot switch was specified on an illegal 
device. 

An error occurred during an attempt to write 
bootstrap with /U switch. 



A checksum error 
binary transfer. 



occurred in a format ted 



Memory overflow — too many devices and/or file 
specifications (usually *.* operations) and 
no room for buffers. 

No room on device for file. 

Unrecoverable error reading directory. Check 
volume for off-line or write-locked condition 
and try the operation again. 



Unrecoverable error writing directory, 
again. 



Try 
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A /T command attempted to make file smaller. 

An attempt was made to use /0 or /S while a 
foreground job was still in memory. Unload 
it if it is no longer desired. 

File not found during a delete, copy, or re- 
name operation, or no input files with the 
expected name or extension were found during 
a *.* expansion. 
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PILL CMD? 



PILL DEV? 
PILL DIR? 



PILL REN? 

PILL SWT? 
PIN ER? 

POUT ER? 



POUT FIL? 
PROOM? 



The command specified was not syntactically- 
correct; a device name is missing which 
should be specified, a switch argument is too 
large, a filename is specified where one is 
inappropriate, or a nonf ile-structured device 
is specified for a file-structured operation. 

Illegal or nonexistent device. 

The device did not contain a properly ini- 
tialized directory structure (EOT file on 
magtape and cassette; empty file directory 
on other devices). Use /Z. 

Illegal rename operation. Usually caused by 
different device names on the input and out- 
put sides of the command string. 

Illegal switch or switch combination. 

Unrecoverable error reading file. Try again 
(this error is ignored during /G operation) . 

Unrecoverable error writing file. Perhaps a 
hardware or checksum error; try recopying 
file. Also may be caused by an attempt to 
compress a larger device to a smaller one or 
by not enough room when creating a file. The 
system takes the largest space available and 
divides it in half before attempting to in- 
sert the file. Try the [n] construction or 
/X switch. 

Illegal output file specification or missing 
output file. 

Insufficient space following file specified 
with a /T switch. 



The following warning messages are output by PIP: 
CTn: PUSH REWIND OR MOUNT NEW VOLUME 



?N0 .SYS/. BAD 
ACTION? 



? REBOOT? 



A new cassette must be mounted on drive n to 

allow continuation of an I/O operation. The 

operation is continued automatically as soon 
as the new cassette is mounted. 

The /Y switch was not included with a command 
specified on a .SYS or .BAD file. The com- 
mand is executed for all but the .SYS and 
.BAD files. A *.* transfer is most likely 
to cause this message. 

•SYS files have been transferred, renamed, 
compressed or deleted from the system device. 
It may be necessary to reboot the system. 

NOTE 

The message is typed immediately 
after execution of the relevant 
command has begun, but the actual 
reboot operation must not be per- 
formed until PIP returns with the 
prompting asterisk for the next 
command. If the system is halted 
and rebooted before the prompting 
asterisk returns, disk information 
may be lost. 
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If any of the .SYS files in use by the 
current system (MONITR.SYS and handler files) 
have been physically moved on the system 
device, it is necessary to reboot the system 
immediately. If not, this message can be 
ignored. If the cause of the message was a 
/S operation, the system need be rebooted 
only if there was an empty space before any 
of the .SYS files or if the /H:n switch was 
used to increase the number of directory 
segments. The need to reboot can be 
permanently avoided by placing all .SYS files 
at the beginning of the system device, then 
avoiding their involvements in PIP operations 
by not using the /Y switch. 

dev:/Z ARE YOU SURE? 

Confirmation must be given by the user before 
a device can be zeroed. 
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CHAPTER 5 
MACRO ASSEMBLER 

MACRO is a 2-pass macro assembler requiring an RT-11 system 
configuration (or background partition) of 12K or more. Macros are 
instructions in a source or command language which are equivalent to a 
specified sequence of machine instructions or commands. Users with 
minimum memory configurations must use ASEMBL and EXPAND and should 
read this chapter and Chapters 10 and 11 before assembling any 
programs. (The macro features not supported by ASEMBL are indicated 
in this chapter; many of the features not available in ASEMBL are 
supported by EXPAND.) 

Some notable features of MACRO are: 

1. Program control of assembly functions 

2. Device and file name specifications for input and output 
files 

3. Error listing on command output device 

4. Alphabetized, formatted symbol table listing 

5. Relocatable object modules 

6. Global symbols declaration for linking among object modules 

7. Conditional assembly directives 

8. Program sectioning directives 

9. User defined macros 

10. Comprehensive set of system macros 

11. Extensive listing control, including cross reference listing 
Operating instructions for the MACRO assembler appear in Section 5.7. 
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5.1 SOURCE PROGRAM FORMAT 

A source program is composed of a sequence of source lines; each 

source line contains a single assembly language statement followed by 

a statement terminator. A terminator may be either a line feed 

character (which increments the line count by 1) or a form feed 

character (which resets the line count and increments the page 
count by 1) . 



NOTE 

EDIT automatically appends a line feed 
to every carriage return encountered in 
a source program. For listing format, 
MACRO automatically inserts a carriage 
return before any line feed or form feed 
not already preceded by one. 



An assembly language line can contain up to 132 (decimal) characters 
(exclusive of the statement terminator) . Beyond this limit, excess 
characters are ignored and generate an error flag. 



5.1.1 Statement Format 

A statement can contain up to four fields which are identified by 
order of appearance and by specified terminating characters. The 
general format of a MACRO assembly language statement is : 



label : 



operator operand (s) ; comments 



The label and comment fields are optional. The operator and operand 
fields are interdependent; either may be omitted depending upon the 
contents of the other. 

The assembler interprets and processes these statements one by one, 
generating one or more binary instructions or data words or performing 
an assembly process. A statement contains one of these fields and may 
contain all four types. Blank lines are legal. 

Some statements have one operand, for example: 

CL.R R0 

while others have two: 



MOV 



*344,R2 



An assembly language statement must be complete on one source lin.. 
No continuation lines are allowed. (If a continuation is attempted 
with a line feed, the assembler interprets this as the statement 
terminator. ) 

MACRO source statements may be formatted with EDIT so that use of the 
TAB character causes the statement fields to be aligned. For example: 
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Label 
Field 

CHECK: 



EVEN: 



Operator 
Field 

BIT 
BEQ 
MOV 
RTS 



Operand 
Field 

#1,R0 
EVEN 

#-l,ODDFLG 
PC 



Comment 
Field 

;IS NUMBER ODD? 
;NO, IT'S EVEN 
;ELSE SET FLAG 
; RETURN 



5.1.1.1 Label Field - A label is a user-defined symbol that is 
unique within the first six characters and is assigned the value of 
the current location counter and entered into the user-defined symbol 
table. The value of the label may be either absolute (fixed in memory 
independently of the position of the program) or relocatable (not 
fixed in memory) , depending on whether the location counter value (see 
Section 5.2.6) is currently absolute or relocatable. 

A label is a symbolic means of referring to a specific location within 
a program. If present, a label always occurs first in a statement and 
must be terminated by a colon. For example, if the current location 
is absolute 100 (octal), the statement: 



ABCDl 



MQV 



A,B 



assigns the value 100 (octal) to the label ABCD. Subsequent reference 
to ABCD references location 100 (octal). In this example if the 
location counter was declared relocatable within the section, the 
final value of ABCD would be 100 (octal) plus a value assigned by LINK 
when it relocates the code, called the relocation constant. (The 
final value of ABCD would therefore not be known until link- time. 
This is discussed later in this chapter and in Chapter 6.) 

More than one label may appear within a single label field, in which 
case each label within the field is assigned the same value. For 
example, if the current location counter is 100 (octal) , the multiple 
labels in the statement: 



ABCI 



ER*EX| MASKI 



MOV 



A,B 



cause each of the three labels — ABC, ERREX, and MASK — to be equated to 
the value 100 (octal). 

A symbol used as a label may not be redefined within the user program. 
An attempt to redefine a label results in an error flag in the 
assembly listing. 



5.1.1.2 Operator Field - An operator field follows the label field 
in a statement and may contain a macro call, an instruction mnemonic, 
or an assembler directive. The operator may be preceded by zero, one 
or more labels and may be followed by one or more operands and/or a 
comment. Leading and trailing spaces and tabs are ignored. 

When the operator is a macro call, the assembler inserts the 
appropriate code to expand the macro. When the operator is an 
instruction mnemonic, it specifies the instruction to be generated and 
the action to be performed on any operand (s) which follow. When the 
operator is an assembler directive, it specifies a certain function or 
action to be performed during assembly. 
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An operator is legally terminated by a space, tab, or any 
non-alphanumeric character (symbol component) . 

Consider the following examples: 

MOV A,B (space terminates the operator MOV) 
mov#a,b (y terminates the operator MOV) 

When the statement line does not contain an operand or comment, the 
operator is terminated by a carriage return followed by a line feed or 
form feed character. 

A blank operator field is interpreted as a .WORD assembler directive 
(See Section 5.5.3.2). 



5.1.1.3 Operand Field - An operand is that part of a statement which 
is manipulated by the operator. Operands may be expressions, numbers, 
or symbolic or macro arguments (within the context of the operation) . 
When multiple operands appear within a statement, each is separated 
from the next by one of the following characters: comma, tab, space, 
or paired angle brackets around one or more operands (see Section 
5.2.1.1). Multiple delimiters separating operands are not legal (with 
the exception of spaces and tabs— any combination of spaces and/or 
tabs represents a single delimiter) . An operand may be preceded by an 
operator, a label or another operand and followed by a comment. 

The operand field is terminated by a semicolon when followed by a 
comment, or by a statement terminator when the operand completes the 
statement. For example: 

LABfcll MOV A,B /COMMENT 

The space between MOV and A terminates the operator field and begins 
the operand field; a comma separates the operands A and B; a 
semicolon terminates the operand field and begins the comment field. 



5.1.1.4 Comment Field - The comment field is optional and may 
contain any ASCII characters except null, rubout, carriage return, 
line feed, vertical tab or form feed. All other characters, even 
special characters with defined usage, are ignored by the assembler 
when appearing in the comment field. 

The comment field may be preceded by one, any, none or all of the 
other three field types. Comments must begin with the semicolon 
character and end with a statement terminator. 
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Comments do not affect assembly processing or program execution, but 
are useful in source listings for later analysis, debugging, or 
documentation purposes . 



5.1.2 Format Control 

Horizontal or line formatting of the source program is controlled by 
the space and tab characters. These characters have no effect on the 
assembly process unless they are embedded within a symbol, number, or 
ASCII text; or unless they are used as the operator field terminator. 
Thus, these characters can be used to provide an orderly source 
program. A statement can be written: 

IA8EL«M0V(SP)*,TAG|P0P V AL.UE OFF STACK 
or, using formatting characters, it can be written: 

LABfcLI MOV (8P3+,TAG FPOP VALUE OFF STACK 

which is easier to read in the context of a source program listing. 

Vertical formatting, i.e., page size, is controlled by the form feed 
character. A page of n lines is created by inserting a form feed 
(CTRL FORM) after the nth line. (See also Section 5.5.1.6 for a 
description of page formatting with respect to macros and Section 
5.5.1.2 for a description of assembly listing output.) 



5.2 SYMBOLS AND EXPRESSIONS 

This section describes the various components of legal MACRO 
expressions: the assembler character set, symbol construction, 
numbers, operators, terms and expressions. 



5.2.1 Character Set 

The following characters are legal in MACRO source programs : 

1. The letters A through Z. Both upper- and lower-case letters 
are acceptable, although, upon input, lower-case letters are 
converted to upper-case letters. Lower-case letters can only 
be output by sending their ASCII values to the output device. 
This conversion is not true for .ASCII, .ASCIZ, ' (single 
quote) or n (double quote) statements if .ENABL LC is in 
effect. 

2. The digits through 9. 

3. The characters . (period or dot) and $ (dollar sign) which 
are reserved for use in system program symbols (with the 
exception of local symbols; see Section 5.2.5). 

4. The following special characters: 
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Character 


Designation 


carriage return 
line feed 
form feed 
vertical tab 




% 
tab 




colon 

equal sign 
percent sign 


space 

# 

e 
( 

) 

9 

/ 

< 




number sign 

at sign 

left parenthesis 

right parenthesis 

comma 

semicolon 

left angle bracket 


> 




right angle bracket 


+ 




plus sign 


- 




minus sign 


* 




asterisk 


/ 
& 
! 

n 
1 

t 




slash 
ampersand 
exclamation 
double quote 
single quote 
uparrow 



\ 



backslash 



Function 
formatting character 
source statement terminators 



label terminator 

direct assignment indicator 

register term indicator 

item or field terminator 

item or field terminator 

immediate expression indicator 

deferred addressing indicator 

initial register indicator 

terminal register indicator 

operand field separator 

comment field indicator 

initial argument or expression 

indicator 

terminal argument or expression 

indicator 

arithmetic addition operator or 

auto increment indicator 

arithmetic subtraction operator 

or auto decrement indicator 

arithmetic multiplication 

operator 

arithmetic division operator 

logical AND operator 

logical inclusive OR operator 

double ASCII character indicator 

single ASCII character indicatoir 

universal unary operator, 

argument indicator 

macro numeric argument indicator 

(not available in ASEMBL) 



5.2.1.1 Separating and Delimiting Characters - Reference is made in 
the remainder of the chapter to legal separating characters and macro 
argument delimiters. These terms are defined in Table 5-1 and 
following. 

Table 5-1 
Legal Separating Characters 



Character 


Definition 


Usage 


space 
i 


one or more spaces 
and/or tabs 

comma 

paired angle brackets 


A space is a legal separator 
only for argument operands. 
Spaces within expressions are 
ignored. 

A comma is a legal separator 
for both expressions and 
argument operands. 

Paired angle brackets are used 
to enclose an argument, 



(Continued on next page) 
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Table 5-1 (cont.) 
Legal Separating Characters 



Character 


Definition 


Usage 


t\...\ 


Up arrow construction 
where the up arrow 
character is followed 
by an argument 
bracketed by any paired 
printing characters. 


particularly when that 
argument contains separating 
characters. Paired angle 
brackets may be used anywhere 
in a program to enclose an 
expression for treatment as a 
term. (The angle bracket 
construction should be used 
when the argument contains 
unary operators.) 

This construction is 
equivalent in function to the 
paired angle brackets and 
is generally used only where 
the argument contains angle 
brackets. 



Macro arguments may appear in several forms to allow for special 
cases. The rules to observe when separating arguments are: 

1. If an argument string contains only non-separating characters 
(those not defined in Table 5-1) and no spaces, then it may 
appear in the argument list separated, if necessary, from the 
other arguments by commas . 

2. If an argument string contains separating characters or 
spaces, but does not contain the characters < or > (left or 
right angle brackets) , then the argument may appear enclosed 
in paired angle brackets (e.g., <argument string>) . The 
paired angle brackets are removed before the argument string 
is used. Successive pairs of angle brackets may be used to 
enclose an argument; only the outermost pair is removed. 

3. If an argument string contains separating characters or 
spaces (possibly including the left or right angle bracket 
characters) , then it may appear in the following form: 
t\argument string\ where the backslashes may be replaced by 
any character not appearing in the argument string. The 
uparrow and backslashes (or other character) are removed 
before the argument string is substituted into the text. 



Note that regardless of the method used to specify an argument, 
must be separated from any other arguments by commas. 



it 



5.2.1.2 Illegal Characters - A character can be illegal in one of 
two ways : 

1. A character which is not recognized as an element of the 
MACRO character set is always an illegal character and causes 
immediate termination of the current line at that point, plus 
the output of an error flag in the assembly listing. For 
example : 

LABEL*-* A: MOV A,B 

Since the backarrow is not a recognized character, the entire 
line is treated as a: 



.WORD LABEL 

statement and is flagged in the listing. 
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2. A legal MACAO character may be illegal in context. Such 
character generates a Q error on the assembly listing. 



5.2.1.3 Operator Characters - Under MACRO, legal unary 
(operators applying to only one operand) are as follows: 



operators 



Unary 
Operator 



Explanation 
plus sign 

minus sign 



uparrow, universal 
unary operator 
(this usage is 
described in 
greater detail 
in Sections 
5.5.4.2 and 5.5.6.2) 



+A 



-A 



Example 

(positive value 
equivalent to A) 

(negative, 2's 
value of A) 



of 



A, 



complement „ 



tF3.0 



tC24 



tD127 



t034 



tBHOOOlll 



(interprets 3.0 as a 
1-word floating-point 
number) 



(interprets the one's 
complement of the binary 
representation of 24(8)) 

(interprets 127 as a decimal 
number) 



(interprets 34 as 
number) 



an octal 



(interprets 11000111 as a 
binary value) 



The unary operators described above can be used adjacent to each other 
in a term. For example: 





tCt012 
-t05 






Legal binary operators under 


MACRO 


are as follows : 


Binary 
Operator 


Explanation 




Example 


+ 

* 

/ 
& 
1 


addition 
subtraction 
multiplication 
division 
logical AND 
logical inclusive 


OR 


A+B 

A-B 

A*B (16-bit product returned) 

A/B (16-bit quotient returned) 

A&B 

AIB 



All binary operators have the same priority. Division and 
multiplication are signed operations. Items can be grouped for 
evaluation within an expression by enclosure in angle brackets. Terms 
in angle brackets are evaluated first, and remaining operations are 
performed left to right. For example: 

.WORD 1+2*3 »1S 11 OCTAL 
.WORD U«2*3» (IS 7 OCTAL 
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5.2.2 Symbols 

There are three types of symbols: permanent, user-defined and . macro. 
MACRO maintains three types of symbol tables: the Permanent Symbol 
Table (PST) , the User Symbol Table (UST) and the Macro Symbol Table 
(MST) . The PST contains all the permanent symbols and is part of the 
MACRO Assembler load module. The UST and MST are constructed as the 
source program is assembled; user-defined symbols are added to the 
table as they are encountered. 



5.2.2.1 Permanent Symbols - Permanent symbols consist of the 
instruction mnemonics (Appendix C) and assembler directives and macro 
directives (sections 5.5 and 5.6, Appendix C) . These symbols are a 
permanent part of the assembler and need not be defined before being 
used in the source program. 



5.2.2.2 User-Defined and Macro Symbols - User-defined symbols are 
those used as labels or defined by direct assignment (Section 5.2.3). 
These symbols are added to the User Symbol Table as they are 
encountered during the first pass of the assembly. Macro symbols are 
those symbols used as macro names in the operator field (Section 
5.6.1). These symbols are added to the Macro Symbol Table as they are 
encountered during the assembly. 

User-defined and macro symbols can be composed of alphanumeric 
characters, dollar signs, and periods only; any other character is 
illegal. 

The $ and . characters are reserved for system software symbols (for 
example, the system macro symbol .READ) ; it is recommended that $ and 
. not be inserted in user-defined or macro symbols. 

The following rules apply to the creation of user-defined and macro 
symbols : 

1. The first character must not be a number (except in the case 
of local symbols, see Section 5.2.5). 

2. Each symbol must be unique within the first six characters. 

3. A symbol can be written with more than six legal characters, 
but the seventh and subsequent characters are only checked 
for legality, and are not otherwise recognized by the 
assembler. 

4. Spaces, tabs, and illegal characters must not be embedded 
within a symbol. 

The value of a symbol depends upon its use in the program. A symbol 
in the operator field may be any one of the three symbol types. To 
determine the value of the symbol, the assembler searches the three 
symbol tables in the following order: 

1. Macro Symbol Table 

2. Permanent Symbol Table 

3. User-Defined Symbol Table 
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A symbol found in the operand field is sought in the: 

1. User-Defined Symbol Table 

2. Permanent Symbol Table 

in that order. The assembler never expects to find a macro name in an 
operand field. 

These search orders allow redefinition of Permanent Symbol Table 
entries as user-defined or macro symbols. The same name can be 
assigned to both a macro and a label. 

User-defined symbols are either internal or external (global) . All 
user-defined symbols are internal unless explicitly defined as being 
global with the .GLOBL directive (see Section 5.5.10). 

Global symbols provide links between object modules. A global symbol 
defined as a label is generally called an entry point (to a section 
of code) . Such symbols are referenced from other object modules to 
transfer control throughout the load module (which may be composed of 
a number of object modules) . 

Since MACRO provides program sectioning capabilities (Section 5.5.9) , 
two types of internal symbols must be considered: 

1. Symbols that belong to the current program section, and 

2. Symbols that belong to other program sections. 

In both cases, the symbol must be defined within the current assembly; 
the significance of the distinction is critical in evaluating 
expressions involving type (2) above (see Section 5.2.9). 



5.2.3 Direct Assignment 

A direct assignment statement associates a symbol with a value. When 
a direct assignment statement defines a symbol for the first time, 
that symbol is entered into the user symbol table and the specified 
value is associated with it. A symbol may be redefined by assigning a 
new value to a previously defined symbol. The latest assigned value 
replaces any previous value assigned to a symbol. 

The general format for a direct assignment statement is: 

symbol = expression 

Symbols take on the relocatable or absolute attribute of their 
defining expression. However, if the defining expression is global, 
the symbol is not global unless explicitly defined as such in a .GLOBL 
directive. For example: 

A»l |THE SYMBOL A IS EQUATED TO THE 

»VALUE i 

B»'A-UMASKL0W »THE SYMBOL B IS EQUATED TO THE 
JVALUE OF THE EXPRESSION 

CI DO |THE SYMBOL D IS EQUATED TO 3 
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e: 



MOV #|,»BIE H.ABELS C AND E ARE EQUATED TO THE 
ILOCATION OF THE MOV COMMANQ 



The following conventions apply to direct assignment statements: 

1. An equal sign (=) must separate the symbol from the 
expression defining the symbol value. 

2. A direct assignment statement is usually placed in the 
operator field and may be preceded by a label and followed by 
a comment. 



NOTE 

If the program jumps to or references 
the label of a direct assignment 
statement, it is actually referencing 
the following instruction statement. 
For example: 

CI D«3 

El MOV #D,ABLE 



JMP C 
This code causes a jump to the label E. 



3. Only one symbol can be defined by any one direct assignment 
statement. 

4. Only one level of forward referencing is allowed. That is, 
the following arrangement is illegal: 

X = Y 

Y = Z 

Z = 1 

X and Y are both undefined throughout pass 1. X is undefined 
throughout pass 2 and causes an error flag in the assembly 
listing. 



5.2.4 Register Symbols 

The eight general registers of the PDP-11 are numbered through 7 and 
can be expressed in the source program as: 

%0 
%1 



%7 
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The digit indicating the specific register can be replaced by any 
legal tern which can be evaluated during the first assembly pass. 

It is recommended that the programmer create and use symbolic names 
for all register references. A register symbol may be defined in a 
direct assignment statement among the first statements in the program. 
A register symbol cannot be defined after the statement which uses it. 
The defining expression of a register symbol must be absolute. For 
example : 

R0»X0 JREGISTER DEFINITION 

R1«X1 

R2«X2 

R3»X3 

R4«X« 

R5»X5 

3P«Xfc 

PC«X7 

The symbolic names assigned to the registers in the example above are 
the conventional names used in all PDP-11 system programs. Since 
these names are fairly mnemonic, it is suggested the user follow this 
convention. Registers 6 and 7 are given special names because of 
their special functions, while registers through 5 are given similar 
names to denote their status as general purpose registers. 

All register symbols must be defined before they are referenced. A 
forward reference to a register symbol causes phase errors in an 
assembly. 

The % character can be used with any term or expression to specify a 
register. (A register expression less than or greater than 7 is 
flagged with an R error code.) For example: 

CLR X3*l 
is equivalent to: 

CUR X« 
and clears the contents of register 4, while: 

CLR u 

clears the contents of memory address 4. 

In certain cases a register can be referenced without the use of a 
register symbol or register expression; these cases are recognized 
through the context of the statement. An example is shown below: 

JSR 5,SUBR IFIRST OPERAND FIELO MUST ALWAYS 
I BE A REGISTER 



5.2.5 Local Symbols 

Local symbols are specially formatted symbols used as labels within a 
given range. 
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Local symbols provide a convenient means of generating labels to be 
referenced by branch instructions. Use of local symbols reduces the 
possibility of multiply-defined symbols within a user program and 
separates entry point symbols from local references. Local symbols, 
then, are not referenced from other object modules or even from 
outside their local symbol block. 

Local symbols are of the form n$, where n is a decimal integer from 1 
to 127, inclusive, and can only be used on word boundaries. Local 
symbols include : 

1$ 

27$ 

59$ 

104$ 

Within a local symbol block, local symbols can be defined and 

referenced. However, a local symbol cannot be referenced outside the 

block in which it is defined. There is no conflict with labels of the 
same name in other local symbol blocks. 

Local symbols 64$ through 127$ can be generated automatically as a 
feature of the macro processor (see Section 5.6.3.5 for further 
details) . When using local symbols the user is advised to first use 
the range from 1$ to 63$. 

A local symbol block is delimited in one of the following ways: 

1. The range of a single local symbol block can consist of those 
statements between two normally constructed symbolic labels. 
(Note that a statement of the form: 

LABEL=. 

is a direct assignment, does not create a label in the strict 
sense, and does not delimit a local range.) 

2. The range of a local symbol block is terminated upon 
encountering a .CSECT directive. 

3. The range of a single local symbol block can be delimited 
with .KNABL LSB and the first symbolic label or .CSECT 
directive following the .DSABL LSB directives. The default 
for LSB is off. 

For examples of local symbols and local symbol blocks, see Figure 5-1. 

The maximum offset of a local symbol from the base of its local symbol 
block is 128 decimal words. Symbols beyond this range are flagged 
with an A error code. 
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5.2.6 Assembly Location Counter 

The period (.) is the symbol for the assembly location counter. When 
used in the operand field of an instruction, it represents the address 
of the first word of the instruction. When used in the operand field 
of an assembler directive, it represents the address of the current 
byte or word. For example: 

*» MOV #.,R6> >. REFERS TO LOCiTlO* * , 

II. E., THE ADDRESS OF THE 

JMOV INSTRUCTION 

(# is explained in Section 5.4.9). 

At the beginning of each assembly pass, the assembler clears the 
location counter. Normally, consecutive memory locations are assigned 
to each byte of object data generated. However, the location where 
the object data is stored may be changed by a direct assignment 
statement altering the location counter: 

.=expression 

The expression defining the location counter must not contain forward 
references or symbols that vary from one pass to another. If an 
expression is assigned to the current location counter in a 
relocatable CSECT, an error flag is generated. (The construction 
,=.+expression must be used.) 

Similar to other symbols, the location counter symbol has a mode 
associated with it, either absolute or relocatable; the mode cannot 
be external. The existing mode of the location counter cannot be 
changed by using a defining expression of a different mode. 



5-14 



MACRO Assembler 



Line Octal 
Number Expansion 



Source Code 



Comments 



000000 
000000 



t 
2 
3 

n 

5 

6 

7 

8 

9 

10 

11 

12 00000 

13 

U 00000 

15 

16 00000 

17 

IS 

19 00000 

20 00000 

21 00004 

22 00006 

23 00012 
24 

25 

26 00000 

27 00000 

28 00004 

29 00006 

30 00012 
31 

32 

33 00000 

34 00000 

35 00004 

36 00006 

37 00012 
38 

39 

40 00000 

41 



000000 
000000' 

000000' 
000000' 
0100000* 



IMPURE' 
iMPPASl 



IMPLINI 



XCTPRGI 

012700 
000000' 
005020 111 
022700 

000000' 

1*1374 

000000' 

XCTPA8I 
012700 
000000' 
005020 1SI 
022700 
0100000' 
101374 

000000' 

XCTLINI 
012700 
000000' 
005020 1SI 
0<22700 
000000' 
101374 

000000' 

000000 IMPTOPJ 
000001' 



.MCALL ,RESDEF,.,V2., 

.REGOEF 

• * V2» , 

R0"X0 

.sbttl sector initialization 

.csect impure iimpure storage area 

.csect imppa3 (cleared each pass 



.CSECT IMPUIN 
.CSECT XCTPRG 



MOV 

CLR 

CMP 

BHI 



CLR 

CMP 

BHI 



CLR 

CMP 

BHI 



#IMPURE,R0 

(R0)* 
#IMPTOP,R0 

IS 



.CSECT XCTPA8 

MOV #IMPPAS # R0 



(R0) + 
#IMPTOP,R0 

IS 



.CSECT XCTLIN 
MOV #IMPLIN f R0 



(R0)* 
•IMPTOP,R0 

IS 



, CSECT MIXED 
.WORD 
.END 



ICLEARED EACH LINE 

IPR08RAM 
IINITIALI2ATI0N 



(CLEAR IMPURE AREA 



(PASS INITIALIZATION 



(CLEAR IMPURE PART 



ILINE INITIALIZATION 



(MIXED MODE SECTOR 



Figure 5-1 
Assembly Source Listing of MACRO Code Showing Local Symbol Blocks 
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The mode of the location counter symbol can be changed by the 
the .ASECT or .CSECT directive as explained in Section 5.5.9. 



use of 



Examples : 



.ASECT 



,■300 



FIRSTI MOV ,+10, COUNT 

COUNT! .WORD 
,-320 

SECONOI MOV ., INDEX 



INDEX! .WORD 



(SET LOCATION COUNTER TO 
•ABSOLUTE 300 

(THE LABEL FIRST HAS THE VALUE 

(500(8) 

I, + 10 EQUALS 510(8), THE 

•CONTENTS OF THE LOCATION 

1510(8) WILL BE DEPOSITED 

IIN LOCATION COUNT, 

(THE ASSEMBLY LOCATION COUNTER 
(NOW HAS A VALUE OF 
(ABSOLUTE 320(8). 

(THE LABEL SECOND HAS THE 
(VALUE 520(8) 
(THE CONTENTS OF LOCATION 
1520(8), THAT ISi THE BINARY 
(CODE FOR THE INSTRUCTION 
IITSELF WILL BE DEPOSITED IN 
ILOCATION INDEX, 



,C»ECT 
.■.♦20 

THIRDI .WORD 



(SET LOCATION COUNTER TO 
(RELOCATABLE 28 OF THE 
(UNNAMED PR06RAM SECTION, 

ITHE LABEL THIRD HAS THE 
(VALUE OF RELOCATABLE 20, 



Storage area may be reserved by advancing the location counter. For 
example, if the current value of the location counter is 1000, the 
direct assignment statement: 

,■,♦100 

reserves 100 (octal) bytes of storage space in the program. The next 
instruction is stored at 1100. (The .BLKW and .BLKB directives can 
also be used to reserve blocks of storage; see Section 5.5.5.3.) 
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5.2.7 Numbers 

The MACRO Assembler assumes all numbers in the source program are to 
be interpreted in octal radix unless otherwise specified. The assumed 
radix can be altered with the .RADIX directive or individual numbers 
can be treated as being of decimal, binary, or octal radix (see 
Section 5.5.4.2) . 

Octal numbers consist of the digits through 7 only. A number not 
specified as a decimal number and containing an 8 or 9 is flagged with 
an N error code and treated as a decimal number. 

Negative numbers are preceded by a minus sign (the assembler 
translates them into two's complement form). Positive numbers may be 
preceded by a plus sign, although this is not required. 

A number which is too large to fit into 16 bits (177777<n) is 
truncated from the left and flagged with a T error code in the 
assembly listing. 

Numbers are always considered absolute quantities (that is, not 
relocatable) . 

The single-word floating-point numbers which can be generated with the 
tF operator (see Section 5.5.6.2) are stored in the following format: 

15 14 7 6 



SIGN 
BIT 


8- BIT EXPONENT 


7-BIT MANTISSA 



Refer to PDP-11/45 Processor Handbook for details of the 
floating-point format. 



5.2.8 Terms 

A term is a component of an expression. A term may be one of the 
following: 

1. A number whose 16-bit value is used. 

2. A symbol that is interpreted according to the following 
hierarchy: 

a. a period that causes the value of the current location 
counter to be used 

b. a permanent symbol whose basic value is used and whose 
arguments (if any) are ignored 

c. user defined symbols 

d. an undefined symbol that is assigned a value of zero and 
inserted in the user-defined symbol table 
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3. An ASCII conversion using either an apostrophe followed by a 
single ASCII character or a double quote followed by two 
ASCII characters, which results in a word containing the 
7-bit ASCII value of the character (s) . (This construction is 
explained in greater detail in Section 5.5.3.3.) 

4. An expression enclosed in angle brackets. Any quantity 
enclosed in angle brackets is evaluated before the remainder 
of the expression in which it is found. Angle brackets are 
used to alter the left to right evaluation of expressions 
(for example, to differentiate between A*B+C and A*<B+C>) or 
to apply a unary operator to an entire expression (-<A+B>). 



5.2.9 Expressions 

Expressions are combinations of terms that are joined together by 
binary operators and that reduce to a 16-bit value. The operands of a 
.BYTE directive are evaluated as word expressions before truncation to 
the low-order eight bits. Prior to truncation, the high-order byte 
must be zero or all ones (when the byte value is negative, the sign 
bit is propagated) . The evaluation of an expression includes the 
evaluation of the mode of the resultant expression — that is, absolute, 
relocatable or external. Expression modes are defined further below. 

Expressions are evaluated left to right with no operator hierarchy 
rules except that unary operators take precedence over binary 
operators. A term preceded by a unary operator can be considered as 
containing that unary operator. (Terms are evaluated, where 
necessary, before their use in expressions.) Multiple unary operators 
are valid and are treated as follows: 

-+-A 

is equivalent to: 

-<+<-A>> 

The value of an external expression is the value of the absolute part 
of the expression; e.g., EXT+A has a value of A. This is modified by 
the Linker to become EXT+A,, 

Expressions, when evaluated, are either absolute, relocatable, or 
external. For the programmer writing position independent code, the 
distinction is important. 

1. An expression is absolute if its value is fixed. An 
expression whose terms are numbers and ASCII conversions has 
an absolute value. A relocatable expression minus a 
relocatable term, where both items belong to the same program 
section, is also absolute. 

2. An expression is relocatable if its value is fixed relative 
to a base address but will have an offset value added when 
linked. Expressions whose terms contain labels defined in 
relocatable sections and the assembly location counter (in 
relocatable sections) have a relocatable value. 

3. An expression is external (or global) if its value is only 
partially defined during assembly and is completed at link 
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time* An expression whose terms contain a global symbol not 
defined in the current program is an external expression. 
External expressions have relocatable values at execution 
time if the global symbol is defined as being relocatable or 
absolute if the global symbol is defined as absolute. 

An example of the three expression types follows: 



,»100 

ABSSYMn, 



.ASECT 



ITHE VALUE OF AB8SVM IS 
|NQT RELOCATABLE, BECAUSE 
ME ARE IN AN ASECT 



.CSECT MAIN 



ISTART RELOCATABLE 
IPROGKAM SECTION 



.GLOBL EXTVAL 



IEXTVAL IS DEFINED ELSEWHERE, 
UTS VALUE WILL NOT BE KNOWN 
IUNTIL LINK TIME 



BEGSYMt .BLKW U 

.ASCII /ABCD/ 

.EVEN 
ENDSVM*, 



ITHE VALUES OF BEGSYM 
»AN0 ENOSYM ARE 
»REL0CATA8Lfc, BECAUSE 
;THE AODRESS AT WHICH 
|''MAIN« WILL BE LOADED 
IIS NOT DETERMINED UNTIL 
ILINK TIME 



SIZE ■ END3YM-BEGSYM 



IMOWEVER, THE 
IVALUE OF SIZE IS KNOWN 
I (IT IS U.)AT ASSEMBLY 
ITIME AND IS ABSOLUTE 



RELEXP « ENDSYM-BEGSYM*. 



IRELEXP (■,♦12.) IS 
IHELOCATABLE 



EXTEXPI .WORD EXTVALta 



ITHE EXPRESSION "EXTVAL+4" 
IIS EXTERNAL COR GLOBAL) 
IBECAUSE EXTVAL IS DEFINED 
UN ANOTHER PROGRAM UNIT. 



CHARAa'A 



ITHE VALUE OF CHARA 
IIS ABSOLUTE 



5.3 RELOCATION AND LINKING 

The output of the MACRO Assembler is an object module which must be 
processed by LINK before loading and execution (refer to Chapter 6 for 
details). The Linker essentially fixes (i.e., makes absolute) the 
values of external or relocatable symbols and turns the object module 
into a load module. 



To enable the Linker to fix the value of an expression, the assembler 
issues certain directives to the Linker together with required 
parameters. In the case of relocatable expressions, the Linker adds 
the base of the associated relocatable section (the location in memory 
of relocatable 0) to the value of the relocatable expression provided 
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by the assembler. In the case of an external expression, the value of 
the external term in the expression is determined by the Linker (since 
the external symbol must be defined in one of the other object modules 
which are being linked together) and adds it to the value of the 
external expression provided by the assembler. 

All words that are to be modified (as described in the previous 
paragraph) are marked with an apostrophe in the assembly listing. A G 
in the listing indicates that the value is external, or that a global 
is added to that value. Thus, the binary text output looks as 

follows : 



1205065 
000000(1 



CLP 



EXTERNAL(R5) 



IVALUE OF EXTERNAL SYMBOL 

IA8SEMBLE0 ZERO; MILL BE 
IMODIFIEO BY THE LINKER. 



005065 
000006G 



CLR EXTERNAL+6CR5J ITHE ABSOLUTE PORTION OF THE 

/EXPRESSION (0000063 IS ADDER 
IBY THE LINKER TO THE VALUE OF 
ITHE EXTERNAL SYMBOL 



005065 

000000 



CLR RELOCATABLE(RS) 



/ASSUMING WE ARE IN A 

IRELOCATABLE SECTION 

IAND THE VALUE OF RELOCATABLE 

IIS RELOCATABLE «0 



5.4 ADDRESSING MODES 

The program counter (PC, register 7 of the eight general registers) 
always contains the address of the next word to be fetched; i.e., the 
address of the next instruction to be executed, or the second or third 
word of the current instruction. 

In order to understand how the address modes operate and how they 
assemble, the action of the program counter must be understood. The 
key rule is : 

Whenever the processor implicitly uses the program counter 
to fetch a word from memory, the program counter is 
automatically incremented by two after the fetch. 

That is, when an instruction is fetched, the PC is incremented by two 
so that it is pointing to the next word in memory; if an instruction 
uses indexing (Sections 5.4.7, 5.4.9 and 5.4.11) the processor uses 
the program counter to fetch the base from memory. Hence, using the 
rule above, the PC increments by two, and now points to the next word. 

The following conventions are used in this section: 

1. Let E be any expression as defined in Section 5.2. 

2. Let R be a register expression. This is any expression 
containing a term preceded by a % character or a symbol 
previously equated to such a term. 
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Examples : 

R0»X<5 IGENERAL REGISTER 
R1«R0*1 ^GENERAL REGISTER t 
R2M+M IGENERAL REGISTER 2 

3. Let ER be a register expression or an expression in the range 
to 7 inclusive. 

4. Let A be any general address specification which produces a 
6-bit mode address field as described in Sections 3.1 and 3.2 
of the PDP-11 PROCESSOR HANDBOOK (both 11/20 and 11/45 
versions) . 

The addressing specifications, A, can be explained in terms of E, R, 
and ER as defined above. Each is illustrated with the single operand 
instruction CLR or double operand instruction MOV. 



5.4.1 Register Mode 

The register contains the operand. 

Format for As R 

Examples: R0«X0 JDEFINE R0 AS REGISTER 

CLK R0 rCLEAR REGISTER 

5.4.2 Register Deferred Mode 

The register contains the address of the operand. 

Format for A: @R or (ER) 

Examples: CL* #Rl IBOTH INSTRUCTIONS CLEAR 

ITHE WORD AT THE ARQReSS 
CLH CRt) JCONTAINEO IN REGISTER I 

5.4.3 Autoincrement Mode 

The contents of the register are incremented immediately after being 
used as the address of the operand. (See NOTE below.) 
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Format for A: 
Examples : 



(ER) + 

CL« 

CL« 



CL«B 



(R0) + IEACH INSTRUCTION CLEARS 
(R0+3)* FTHE WORD AT THE ADDRESS 
CR83* ICONTAINED IN THE SPECIFIED 
IREGISTIR AND INCREMENTS 
ITHAT REGISTER'S CONTENTS 
»BY TWO, 



(R«)* 



NOTE 



ICLEARS THE BYTE AT THE 
IAODRESS SPECIFIED BY THE 
ICONTENTS OF R4 AND 
INCREMENTS R« BY ONE, 



Both JMP and JSR instructions using 
non-deferred autoincrement mode, 
autoincrement the register before its 
use on the PDP-11/20 and 11/05 (but not 
on the PDP-11/40 or 11/45). In double 
operand instructions of the addressing 
form %R, (R)+ or %R,-(R) where the source 
and destination registers are the same, 
the source operand is evaluated as the 
autoincremented or autodecremented 
value, but the destination register, at 
the time it is used, still contains the 
originally intended effective address. 

In the following two examples, as 
executed on the PDP-11/20, R0 originally 

contains 100. 

MOV R0,(R0)+ fTHE QUANTITY 102 IS MOVED 

|T0 LOCATION 100 

MOV R0,*tR0) fTHE QUANTITY 7fc IS MOVED 

JTO LOCATION 76 

The use of these forms should be avoided 
as they are not compatible with the 
PDP-11/05, 11/40 and 11/45. 

A Z error code is printed with each instruction which is not 
compatible among all members of the PDP-11 family. This is merely a 
warning code. 



5.4.4 Autoincrement Deferred Mode 

The register contains the pointer to the address of the operand, 
contents of the register are incremented after being used. 



The 
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Format for A: 



Example : 



0(FR) + 
CL« 



(PCR3)* ICONTENTS OF REGISTER 3 POINT 
JTO ADDRESS OF WORD TO BE 
ICLEAREO, AND REGISTER 3 IS 
ITHEN INCREMENTED BY TWO 



5.4.5 Autodecrement Mode 

The contents of the register are decremented before being used as 
address of the operand (see NOTE under autoincrement mode) . 



the 



Format for A: - (ER) 
Examples: CL R 



•(R0) »DECREM£NT CONTENTS OF 
-(RB*3) |0, 3, AND 2 BY TWO 
• (R2) IBEFORE USING AS ADDRESSES 
IOF WORDS TO BE CLEARED. 



5.4.C Autodecrement Deferred Mode 

The contents of the register are decremented before being used as 
pointer to the address of the operand. 



the 



Format for A: @-(ER) 
Example: CL^ 



#"(R2) IDECREMENT CONTENTS OF 

IREGISTER 2 BY TWO BEFORE 

fUSING AS A POINTER 

ITO ADDRESS OF WORD TO BE 

ICLEAREO, 



5.4.7 Index Mode 

The value of an expression E is stored as the second or third word of 
the instruction. The effective address is calculated as the value of 
E plus the contents of register ER. The value E is called the base. 



Format for A: E(ER) 



Examples : 



CL« 
CI* 



X+21R1) ^EFFECTIVE ADDRESS IS X*2 PLUS 
ITHE CONTENTS OF REGISTER 1 

•atR3) ^EFFECTIVE ADDRESS IS -2 PLUS 
JTHE CONTENTS OF REGISTER 3, 



5.4.8 Index Deferred Mode 

An expression plus the contents of a register gives the pointer to the 
address of the operand. 



5-23 



MACRO Assembler 



Format for A: 
Example : 



@E(ER) 
C1.R 



#14CR«) IIP REGISTER 4 HOLDS 1013 AND 
HOC lt« HOLDS 2000, 
/LOCATION 2000 18 CLEARED, 



5.4.9 Immediate Mode 

The immediate mode allows the operand itself to be stored as the 
second or third word of the instruction. It is assembled as an 
autoincrement of register 7, the PC. 



Format for A: #E 
Examples: HQV 



MQV 



#10e>,R0 /MOVE AN OCTAL 100 TO 

/REGISTER 
#X,R0 /MOVE THE VALUE OF THE SYMBOL X 

/REGISTER 



TO 



The operation of this mode can be explained by the following example. 
The statement MOV #100, R3 assembles as two words. These are: 

012703 
000100 

Just before this instruction is fetched and executed, the PC points to 
the first word of the instruction. The processor fetches the first 
word and increments the PC by two. The source operand mode is 27 
(autoincrement the PC). Thus, the PC is used as a pointer to fetch the 
operand (the second word of the instruction) before being incremented 
by two, to point to the next instruction. 



5.4.10 Absolute Mode 

Absolute mode is the equivalent of immediate mode deferred. @#E 
specifies an absolute address which is stored in the second or third 
word of the instruction. Absolute mode is assembled as an 
autoincrement deferred of register 7, the PC. 



Format for A: @#E 



Examples: MQV 



CL« 



##100, R0 /MOVE THE VALUE OF CONTENTS 
/OF LOCATION 100 TO 
/REGISTER 0, 

f#X ICLEAR THE CONTENTS OF THE 

/LOCATION WHOSE ADDRESS IS X, 



5.4.11 Relative Mode 

Relative mode is the normal mode for memory references. 
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Format for A: E 

Examples: CL» 100 ICLEAR LOCATION 100 

MOV X,Y jHOV THE CONTENTS OF LOCATION X 
fTO LOCATION Y, 

Relative mode is assembled as index mode, using register 7, the PC, as 
the index register. The base of the address calculation, which is 
stored in the second or third word of the instruction, is not the 
address of the operand (as in index mode) , but the number which, when 
added to the PC, becomes the address of the operand. Thus, the base 
is X-PC, which is called an offset. The operation is explained as 
follows : 

If the statement MOV 100, R3 is assembled at absolute location 20, the 
assembled code is : 

Location 20: 016703 
Location 22: 000 054 

The processor fetches the MOV instruction and adds two to the PC so 
that it points to location 22. The source operand mode is 67, that is, 
indexed by the PC. To pick up the base, the processor fetches the 
word pointed to by the PC and adds two to the PC. The PC now points 
to location 24. To calculate the address of the source operand, the 
base is added to the designated register, that is, BASE+PC=54+2 4=100, 
the operand address. 

Since the assembler considers "." as the address of the first word of 
the instruction, an equivalent index mode statement would be: 

MOV 100-.-4(PC) ,R3 

This mode is called relative because the operand address is calculated 
relative to the current PC. The base is the distance or offset (in 
bytes) between the operand and the current PC. If the operator and 
its operand are moved in memory so that the distance between the 
operator and data remains constant, the instruction will operate 
correctly anywhere in memory. 



5.4.12 Relative Deferred Mode 

Relative deferred mode is similar to relative mode, except that the 
expression, E, is used as the pointer to the address of the operand. 

Format for A: @E 

Example: MQV »X,R0 fMOVE THE CONTENTS OF THE 

(LOCATION WHOSE ADDRESS IS IN 
IX INTO REGISTER 



5.4.13 Table of Mode Forms and Codes 

Each instruction assembles into at least one word. Operands of the 
first six forms listed below do not increase the length of an 
instruction. Each operand in one of the other modes, however, 
increases the instruction length by one word. 
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Form Mode Meaning 

Register mode 
Register deferred mode 
Autoincrement mode 
Autoincrement deferred mode 
Autodecrement mode 
Autodecrement deferred mode 

n represents the register number. 

Any of the following forms adds one word to the instruction length: 

Form Mode Meaning 

E (ER) 6n Index mode 

@E(ER) 7n Index deferred mode 

#E 27 Immediate mode 

@#E 37 Absolute memory reference mode 

E 67 Relative mode 

@E 77 Relative deferred reference mode 

n represents the register number. Note that in the last four forms, 
register 7 (the PC) is referenced. 

NOTE 

An alternate form for @R is (ER) . 
However, the form @(ER) is equivalent to 
00 (ER) . 

The form @#E differs from the form E in 
that the second or third word of the 
instruction contains the absolute 
address of the operand rather than the 
relative distance between the operand 
and the PC. Thus, the instruction 
CLR @#100 clears absolute location 100 
even if the instruction is moved from 
the point at which it was assembled. 
See the description of the .ENABL AMA 
function in Section 5.5.2, which directs 
the assembly of all relative mode 
addresses as absolute mode addresses. 



5.4.14 Branch Instruction Addressing 

The branch instructions are 1-word instructions. The high byte 
contains the op code and the low byte contains an 8-bit signed offset 
which specifies the branch address relative to the PC. Upon execution 
of a branch instruction, the hardware calculates the branch address as 
follows : 

1. Extend the sign of the offset through bits 8-15. 

2. Multiply the result by 2. This creates a word offset rather 
than a byte offset. 
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3. Add the result to the PC to form the final branch address. 

The assembler performs the reverse operation to form the byte offset 
from the specified address. Remember that when the offset is added to 
the PC, the PC is pointing to the word following the branch 
instruction; hence the term -2 in the calculation. 

Byte offset = (E-PC)/2 truncated to eight bits. 

Since PC = .+2, we haves 

Byte offset = (E-.-2)/2 truncated to eight bits. 

NOTE 

It is illegal to branch to a location 
specified as an external symbol, or to a 
relocatable symbol from within an 
absolute section, or to an absolute 
symbol or a relocatable symbol or 
another program section from within a 
relocatable section. 



5.4.15 EMT and TRAP Addressing 

The EMT and TRAP instructions do not use the low-order byte of the 
word. This allows information to be transferred to the trap handlers 
in the low-order byte. If EMT or TRAP is followed by an expression, 
the value is put into the low-order byte of the word. However, if the 
expression is too big (>377(8)) it is truncated to eight bits and a T 
error flag is generated. 



5.5 ASSEMBLER DIRECTIVES 

Directives are statements which cause the assembler to perform certain 
processing operations. 

Assembler directives can be preceded by a label, subject to 
restrictions associated with specific directives, and followed by a 
comment. An assembler directive occupies the operator field of a 
MACRO source line. Only one directive can be placed on any one line. 
Zero, one, or more operands can occupy the operand field; legal 
operands differ with each directive and may be either symbols, 
expressions, or arguments. 



5.5.1 Listing Control Directives 



5.5.1.1 .LIST and .NLIST - Listing options can be specified in the 
text of a MACRO program through the .LIST and .NLIST directives. 
These are of the form: 

.LIST arg 
.NLIST arg 
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where arg represents one or more optional arguments. When used 
without arguments, the listing directives alter the listing level 
count. The listing level count causes the listing to be suppressed 
when it is negative. The count is initialized to zero, incremented 
for each .LIST and decremented for each .NLIST. For example: 

.LIST me 

.MACRO LTE37 ILIST TEST 
IA-THIS LINE SHOULD LIST 

.NLIST 
JB-THI3 LINE SHOULD NOT LIST 

.NLIST 
JC-THIS LINE SHOULD NOT LIST 

.LIST 
>D*THIS LINE SHOULD NOT LIST (LEVEL NOT BACK TO ZERO) 

.LIST 
FE-THIS LINE SHOULD LIST (LEVEL BACK TO ZERO) 

• ENQM 

LTfeST »CALL THE MACRO 

M-THI3 LINE SHOULD LIST 

JE-THIS LINE SHOULD LIST (LEVEL BACK TO ZERO) 

The primary purpose of the level count is to allow macro expansions to 
be selectively listed and yet exit with the level returned to the 
status current during the macro call. 

The use of arguments with the listing directives does not affect the 
level count; however, .LIST and .NLIST can be used to override the 
current listing control. For example: 

,MAC«0 XX 

.LIST ILIST NEXT LINE 

X". 

, NLIST IDO NOT LIST REMAINDER 
|0P MACRO EXPANSION 

.ENDM 

.NLIST ME IDO NOT LIST MACRO EXPANSIONS 

XX 

X". 

Allowable arguments for use with the listing directives are as follows 
(these arguments can be used singly or in combination) : 

Argument Default Function 

SEQ list Controls the listing of source line 

sequence numbers. 

LOC list Controls the listing of the location 

counter (this field would not normally 
be suppressed) . 

BIN list Controls the listing of generated binary 

code (supersedes BEX) . 
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BEX list Controls listing of binary extensions; 

that is, prevents listing those 
locations and binary contents beyond the 
first line of an expansion. This is a 
subset of the BIN argument. 

SRC list Controls the listing of the source code. 

COM list Controls the listing of comments. This 

is a subset of the SRC argument and can 
be used to reduce listing time and/or 
space where comments are unnecessary. 

MD list Controls listing of macro definitions 

and repeat range expansions (has no 
effect in ASEMBL) . 

MC list Controls listing of macro calls and 

repeat range expansions (has no effect 
in ASEMBL) . 

ME no list Controls listing of macro expansions 

(supersedes MEB; has no effect in 
ASEMBL) . 

MEB no list Controls listing of macro expansion 

binary code. A .LIST MEB causes only 
those macro expansion statements 
producing binary code to be listed. 
This is a subset of the ME argument (has 
no effect in ASEMBL) . 

CND list Controls the listing of unsatisfied 

conditions and all .IF and .ENDC 
statements. This argument permits 
conditional assemblies to be listed 
without including unsatisfied code. 

LD no list Controls listing of all listing 

directives having no arguments (those 
used to alter the listing level count) . 

TOC list Controls listing of table of contents on 

pass 1 of the assembly (see Section 
5.5.1.4 describing the .SBTTL 
directive) . The full assembly listing is 
printed during pass 2 of the assembly. 

TTM Terminal Controls listing output format (has no 
mode effect in ASEMBL) . The TTM argument (the 
default case) causes output lines to be 
truncated to 72 characters. Binary code 
is printed with the binary extensions 
below the first binary word. The 
alternative (.NLIST TTM) to Terminal 
mode is line printer mode, which is 
shown in Figure 5-2. 

SYM list Controls the listing of the symbol table 

for the assembly. 
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An example of an assembly listing as sent to a 132-column line printer 
is shown in Figure 5-2. Notice that binary extensions for statements 
generating more than one word are spread horizontally on the source 
line. An example of an assembly listing as sent to an 80-column line 
printer is shown in Figure 5-3 (this is the same format as a terminal 
listing) . Notice that binary extensions for statements generating more 
than one word are printed on subsequent lines. 

Figure 5-4 illustrates a symbol table listing. With the exception of 
local symbols and macro names, all user-defined symbols are listed in 
the symbol table. The characters following the symbols listed have 
special meanings as follows: 

= the symbol is assigned in a direct assignment 
statement 

% the symbol is a register symbol 

R the symbol is relocatable 

G the symbol is global 

The final value of the symbol is expressed in octal. If the symbol is 
undefined six asterisks are printed in place of the octal number. 

CSECT numbers are listed if the symbol is in a named CSECT. All 
CSECTs are listed at the end of the table with their lengths and 
corresponding number. 
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ABSEXPs 


****** Q 




ARGCNTs 


****** G 




ASSEM s 


****** G 




BINCHNa 


000004 




BINDAT 


002322R 


004 


BLKTBLb 


002310R 


004 


BPMB x 


000020 




BUFTBL 


000374RG 


003 


CHAN 


002362R 


004 


CHNSPC 


000312R 


003 


CHRPNT* 


****** G 




CLK50 = 


000040 




CMILENa 


000123 




CNTTBL 


000360RG 


003 


CONFIGs 


000300 




CONT 


000040RG 


010 


CORERR 


001726R 


010 


CPL = 


000120 




CR a 


000015 




CRFBUF 


002076RG 


004 


CRFC = 


000040 




CRFCHN" 


000012 




CRFCNT 


000004RG 


007 


CRFDAT 


002352R 


004 


CRFE a 


000100 




CRFFLG 


000000R 


007 


CRFLENs 


000204 




CRFM a 


000010 




CRFP a 


000020 




CRFPNT 


000064R 


003 


CRFR m 


00000a 




CRF3 s 


020002 




CRFSPC 


0001 14R 


003 


CRFTAB 


000026R 


003 


CRFTST 


000002RG 


007 


CSIERR 


000214R 


003 


CTLTBL 


000000R 


003 


OATE 


001000R 


010 


DATUM 


001004RG 


00a 


DEFEXT 


000104R 


003 


DEVFUL 


000252R 


003 


DIV60 


001240R 


010 


ONC a 


****** G 




EDMASKs 


****** G 




EO.ABSa 


****** G 




EMTERRa 


000052 




ENOP1 a 


****** G 




ENDP2 a 


****** G 




ENDSWT 


000434R 


010 


ERR 


001662R 


010 


ERRB 


000102R 


010 


ERRBTSa 


****** G 




ERRCNTb 


****** G 




EXMFLGs 


****** G 




FF b 


000014 




FILNF 


000264R 


003 


FIN 


001434RG 


010 


FINCL 


001636R 


010 


FINMSG 


001030R 


004 


FINMS1 


001052R 


004 


FJNMS2 


001070R 


004 


FINP1 


000776R 


010 


FINP2 


000776R 


010 


FINSML 


002124RG 


010 


FRECOR 


000006R 


007 


GETPLI 


001756RG 


010 


GETR50B 


****** G 




GSARG s 


****** G 




HORTTL 


001102RG 


004 


HIGHADs 


000050 




ILLCMD 


000226R 


003 


ILLOEV 


000240R 


003 


IMPURT 


000042R 


007 


IMPURS 


000000R 


007 


INIOF 


000106R 


010 
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TIME 


000210R 


003 


TIMTIM 


001016R 


004 


TIMhRD 


000204R 


003 


TMPCNTa 


000014 




TSTSTK 


001704RG 


010 


TTLBRKs 


****** G 




TTLBUFs 


****** G 




TTLLENa 


000040 




TTYBUFs 


000616 




USRLOCs 


000046 




VT = 


000013 




WINIST a 


104240 




WRTERR 


002306R 


010 


XBAW s 


000000 




XEDPICs 


000000 




XMIT0 s 


****** G 




SCLOUT 


003006RG 


.010 


$EDABL= 


****** G 




SFLUSH 


002732RG 


010 


SNLISTb 


****** G 




SREAO 


002422RG 


010 


SREADW 


002422RG 


010 


SWAIT 


002730RG 


010 


SWRITE 


002134RG 


010 


SWRITW 


002134RG 


010 














. ABS. 


000000 
000000 


000 
001 














DPURE 


000000 


002 














OPURES 


000410 


003 














MIXEOS 


002376 


004 














SWTSE$ 


000000 


005 














SWTSEC 


000000 


006 














IMPURS 


000042 


007 














MAINS 


003024 


010 














ERRORS 1 


DETECTED! 

















FREE COREt 13431. 


WORDS 
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Figure 5-4 
Symbol Table 
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5.5.1.2 Page Headings - The MACRO Assembler outputs each page in the 
format shown in Figure 5-3. On the first line of each listing page the 
assembler prints (from right to left) : 

1. title taken from .TITLE directive (most recent one 
encountered) 

2. assembler version identification 

3. the date and time of day if entered 

4. page number 

The second line of each listing page contains the subtitle text 
specified in the last encountered .SBTTL directive. 



5.5.1,3 .TITLE - The .TITLE directive is used to print a heading in 
the output listing and to assign a name to the object, module. The 
heading printed on the first line of each page of the listing is taken 
from the first 31 characters of the argument in the .TITLE directive. 
The first six characters (symbol name) of this same line are also used 
as the name of the object module. These six characters must be 
Radix~50 characters (any characters beyond the first six are ignored) . 
Non-Radix-50 characters are not acceptable. 

For example: 

.TITLE P«QG TO PERFORM OARV ACCOUNTING 

causes PROG TO PERFORM DAILY ACCOUNTIN to be printed in the heading 
for each page and causes the object module of the assembled program to 
be PROG (this name is distinguished from the filename of the object 
module specified in the command string to the assembler) „ 

If there is no TITLE statement, the default name assigned to the first 
object module is: 

.MAIN, 

The first tab or space following the .TITLE directive is not 
considered part of the object module name or header text, although 
subsequent tabs and spaces are significant. 

If there is more than one .TITLE directive, the last .TITLE directive 
in the program conveys the name of the object module. 



5.5.1.4 .SBTTL - The .SBTTL directive is used to provide the 
elements for a printed table of contents of the assembly listing. The 
text following the directive is printed as the second line of each of 
the following assembly listing pages until the next occurrence of a 
„ SBTTL directive. 

j?or example : 

.SBTTL CONDITIONAL ASSEMBLIES 
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The text: 



CONDITIONAL ASSEMBLIES 

is printed as the second line of each of the following assembly 
listing pages. 

During pass 1 of the assembly process, MACRO automatically prints a 
table of contents for the listing containing the line sequence number 
and text of each .SBTTL directive in the program. Such a table of 
contents is inhibited by specifying the .NLIST TOC directive within 
the source. 

An example of a table of contents is shown in Figure 5-5. 



.MAIN. RT-U MACRO VM02-09 
TABLE OF CONTENTS 



5-SEP-74 32130123 



1- 

1- 

2- 

3* 

4- 

5- 

7- 

10- 

11- 

12- 

13- 

14- 

15- 

16- 

17- 

16- 

19- 

20- 

21- 

22- 

23- 

24- 

25- 

26- 

27- 

29- 



29 

37 

1 

i 
t 



RT-ll MACRO PARAMETER FILE 

COMMON PARAMETER FILE 

ASSEMBLY OPTIONS 

VARIABLE PARAMETERS 

GLOBALS 

SECTOR INITIALIZATION 

SUBROUTINE CALL DEFINITIONS 

MISCELLANEOUS MACRO DEFINITIONS 

MCIOCH - I/O CHANNEL ASSIGNMENTS 

****EXEC**** 

PROGRAM START 

INIT OUTPUT FILES 

SWITCH HANDLERS 

END-OF-PASS ROUTINES 

SWITCH AND DATE DATA AREAS 

INIT OUTPUT FILES (CONTINUED) 

FINISH ASSEMBLY AND RESTART 

MEMORY MANAGEMENT 

GET PHYSICAL SOURCE LINE 

SYSTEM MACRO HANDLERS 

WRITE ROUTINES 

READ ROUTINE 

COMMON I/O ROUTINES 

MESSAGES 

I/O TABLES 

FINIS 



Figure 5-5 
Assembly Listing Table of Contents 



Table of Contents text is taken from the text of each .SBTTL 
directive. The associated numbers are the page and line numbers of 
the .SBTTL directives. 
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5.5.1.5 .IDENT - The .IDENT directive is not used or supported by 
the RT-11 system, but is handled by MACRO for compatibility with other 
systems. .IDENT provides a means of labeling the object module 
produced as a result of a MACRO assembly. In addition to the name 
assigned to the object module with the .TITLE directive, a character 
string (up to six characters, treated like a .RAD50 string) can be 
specified between paired delimiters. For example; 

.IDENT /V005A/ 

The character string: 

V005A 

is converted to Radix-50 notation and output to the global symbol 
directory of the object module. 

When more than one .IDENT directive is found in a given program, the 
last .IDENT found determines the symbol which is passed as part of the 
object module identification. 



5.5.1.6 Page Ejection (.PAGE Directive) - There are several means of 
obtaining a page eject in a MACRO assembly listing: 

1. After a line count of 58 lines, MACRO automatically performs 
a page eject to skip over page perforations on line printer 
paper and to formulate terminal output into pages. 

2. A form feed character used as a line terminator (or as the 
only character on a line) causes a page eject. Used within a 
macro definition a form feed character causes a page eject. 
A page eject is not performed when the macro is invoked. 

3. More commonly, the .PAGE directive is used within the source 
code to perform a page eject at that point. The format of 
this directive is: 

.PAGE 

This directive takes no arguments and causes a skip to the 
top of the next page. 

Used within a macro definition, the .PAGE is ignored, but the 
page eject is performed at each invocation of that macro. 



5.5.2 Functions: .ENABL and .DSABL Directives 

Several functions are provided by MACRO through the .ENABL and .DSABL 
directives. These directives use 3-character symbolic arguments to 
designate the desired function and are of the forms: 

.ENABL arg 
.DSABL arg 

where arg is one of the legal symbolic arguments defined below. 
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The following list describes the symbolic arguments and their 
associated functions in the MACRO language: 

Symbolic 

Argument Function 

ABS Enabling of this function (has no effect in 
ASEMBL) produces absolute binary output; 
(i.e., for input to the Paper Tape Software 
System absolute binary loader using a .BIN 
extension instead of .OBJ) . The default case 
is .DSABL ABS. 

AMA Enabling of this function directs the 
assembly of all relative addresses (address 
mode 67) as absolute addresses (address mode 
37) . This switch is useful during the 
debugging phase of program development. 

CDR The statement .ENABL CDR (has no effect in 
ASEMBL) causes source columns 73 and greater 
to be treated as comments. This accommodates 
sequence numbers in card columns 72-80. 

FPT Enabling of this function (has no effect in 

ASEMBL) causes floating point truncation, 

rather than rounding as is otherwise 

performed. .DSABL FPT returns to floating 
point rounding mode. 

LC Enabling of this function causes the 

assembler to accept lower case ASCII input 

instead of converting it to upper case (has 
no effect in ASEMBL) . 

LSB Enable or disable a local symbol block (has 
no effect in ASEMBL) . While a local symbol 
block is normally entered by encountering a 
new symbolic label or .CSECT directive, 
.ENABL LSB forces a local symbol block which 
is not terminated until a label or .CSECT 
directive following the .DSABL LSB statement 
is encountered. The default case is .DSABL 
LSB. 

PNC The statement .DSABL PNC (has no effect in 
ASEMBL) inhibits binary output until an 
•ENABL PNC is encountered. The default case 
is .ENABL PNC. 

An incorrect argument causes the directive containing it to be flagged 
as an error. 



5.5.3 Data Storage Directives 

A wide range of data and data types can be generated with the 
following directives and assembly characters: 
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.BYTE 

.WORD 

i 

n 

.ASCII 

.ASCIZ 

.RAD50 

tB 

tD 

to 



These facilities are explained in the following sections. 



5.5.3.1 .BYTE - The .BYTE directive is used to generate successive 
bytes of data. The directive is of the form: 



.BYTE exp IKH1CH STORES THE OCTAL 

IEQUIVALENT Or THE EXPRESSION 
JEXP IN THE NEXT BYTE 

.BYTE expl,exp2, JWHICH STORES THE OCTAL 

^EQUIVALENTS OF THE LIST 0^ 
IEXPRESSIONS IN SUCCESSIVE BYTES, 



A legal expression must have an absolute value (or contain a reference 
to an external symbol) and must result in eight bits or less of data. 
The 16-bit value of the expression must have a high-order byte (which 
is truncated) that is either all zeros or all ones. Each operand 
expression is stored in a byte of the object program. Multiple 
operands are separated by commas and stored in successive bytes. For 
example s 

SAM>5 

,■,♦410 

,BYTE *D«»e,SAM >060 (OCTAL EQUIVALENT OF 48 

IDECIMAL) IS STORED IN LOCATION 
>4U • 005 IS STORED IN 
IL0CATI0N 411 

If the high-order byte of the expression equates to a value other than 
or -1, it is truncated to the low-order eight bits and flagged with 
a T error code. If the expression is relocatable, an A-type warning 
flag is given. 

At link time it is likely that relocation will result in an expression 
of more than eight bits, in which case, the Linker prints an error 
message,. For example: 



Bl 



•BTTE 23 ISTORES OCTAL 23 IN NEXT BYTE 

•BYTE B IRELOCATABLE VALUE CAUSES AN "A" 
IERR0R FLAG 
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Here, X has an absolute value, 

.6LQBL X 

.BYTE X (STORES 3 IN NEXT BYTE 

and can be linked later with another program: 

.GLOBL » 
.BYTE X 

If an operand following the .BYTE directive is null, it is interpreted . 
as a zero. For example (assume assembly begins at relocatable 0) : | 

.■.♦420 

.BYTE ,, /ZEROS ARE STORED IN BYTES 
1420, 421, AND 482, 



5.5.3.2 .WORD - The .WORD directive is used to generate successive 
words of data. The directive is of the form: 

tW 0R0 exp /WHICH STORES THE OCTAL 

/EQUIVALENT OF THE EXPRESSON 
/EXP IN THE NEXT WORD 

.WQRO expl,exp2... /WHICH STORES THE OCTAL 

/EQUIVALENTS OF THE LIST OF 
/EXPRESSIONS IN SUCCESSIVE 
/WORDS 

where a legal expression must result in 16 bits or less of data. Each 
operand expression is stored in a word of the object program. 

Multiple operands are separated by commas and stored in successive 
words. For example: 

SAL*0 

.•,♦500 

.WORD 177535, .+4, SAL /STORES 177535, 506, AND 

/IN WORDS 590, 502, AND 504, 

If an expression equates to a value of more than 16 bits, it is 
truncated and flagged with a T error code. 

If an operand following the .WORD directive is null, it is interpreted 
as zero. For example: 

,■,♦500 

.WORD ,5, /STORES 0,5,0 IN LOCATIONS 
/500, 502, AND 504 

A blank operator field (any operator not recognized as a macro call, 
op-code, directive or semicolon) is interpreted as an implicit .WORD 
directive. Use of this convention is discouraged. The first term of 
the first expression in the operand field must not be an instruction 
mnemonic or assembler directive unless preceded by a + or - operator. 
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For example: 

,».*<U0 ITHE QP-COOE FOB MOV, WHICH 15 

LABEL! *H0V,L*BEL 1010000. IS STORED IN LOCATION 

man, ane IS STORED IN 

^location am. 

Note that the default .WORD directive occurs whenever there is a. 
leading arithmetic or logical operator, or whenever a leading symbol 
is encountered which is not recognized as a macro call, an instruction 
mnemonic or assembler directive. Therefore, if an instruction 
mnemonic, macro call, or assembler directive is misspelled, the .WORE' 
directive is assumed and errors will result. Assume that MOV is 
spelled incorrectly as MOR: 

MQR A,B 

Two error codes result: A and U. Two words are then generated, one 
for MOR A and one for B. 



5.5.3.3 ASCII Conversion of One or Two Characters - The ' and " 
characters are used to generate text characters within the source 
text. A single apostrophe followed by a character results in a term 
in which the 7-bit ASCII representation of the character is placed in 
the low-order byte and zero is placed in the high-order byte. For 
example : 

MOV #'A,R0 

results in the following 16 bits being moved into RO: 

0000000001000001 

The " character is never followed by a carriage return, null, RUBOUT, 
line feed, or form feed. (For another use of the * character, see 
Section 5.6.3.6.) 

STMNTI 

SET8YM 
SEQ OS 

IC0L0N DELIMITS LABEL FIELD 

IE0UAL DELIMITS 
IASSISNMENT PARAMETER 

A double quote followed by two characters results in a term in which 
the 7-bit ASCII representations of the two characters are placed. For 
example : 

MOV #''AB,R«I 

results in the following binary word being moved into R0 : 

0100001001000001 

Note that the first character is placed in the low-order byte and the 
second character in the high-order byte. 
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SEQ 
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CMPB 


• CHRPNY,(Ml 


BEQ 


LABEL 


CMPB 
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The " character is never followed by a carriage return, null, 
line feed, or form feed. For example: 



rubout , 



IDEVICE NAME TABLE 

DEVNAMI .WORD 

.WORD 

DEVNK6J .WORD 

ui f\ ars 



.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 



«RF IRF DISK 

"RK |RK DISK 

«TT ITERMJNAL KEYBOARD 

"DT IDECTAPE 

"LP JUNE PRINTER 

"PR IPAPER TAPE REAOER 

"PP IPAPER TAPE PUNCH 

JTABIE'S END 



5.5.3.4 .ASCII - The .ASCII directive translates character strings 
into their 7-bit ASCII equivalents for use in the source program. The 
format of the .ASCII directive is: 



.ASCII /character string/ 



where : 



character string 



/ / 



As an example: 



Al 



is a string of any acceptable printing 
ASCII characters including spaces. The 
string may not include null characters, 
rubout, return, line feed, vertical tab, 
or form feed. Nonprinting characters 
can be expressed in digits of the 
current radix and delimited by angle 
brackets. (Any legal, defined 
expression is allowed between angle 
brackets . ) 

are delimiting characters and may be any 
printing characters other than ; < and = 
characters and any character within the 
string. 



.ASCII /HELLO/ 



ISTORES ASCII REPRESENTATION OP 
ITHE LETTERS H E L L IN 
ICONSECUTIVE BYTES 



The order of the characters as they are stored in memory is 
illustrated below. 
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1001 
1003 
1005 
1007 



"^v ->_ 




E 


H 


L 


L 




O 


/ ^~- 





1000 
1002 
1004 
1006 



.ASCII /ABC/«t5>«iB>/DEF/ 
(STORES 
H01rl08rl03,15,12,l04,105,10fc 

HM CONSECUTIVE BYTES 



.ASCII /«AB>/ 



(STORES 74,101,102,76 IN 
(CONSECUTIVE BYTES 



The ; and = characters are not illegal delimiting characters, but are 
preempted by their significance as a comment indicator and assignment 
operator, respectively. For other than the first group, semicolons 
are treated as beginning a comment field. For example: 



Directive 



Result 



.ASCII 


;ABC;/DEF/ 


A B C D E F 


.ASCII 


/ABC/;DEF; 


ABC 


.ASCII 


/ABC/=DEF= 


A B C D E F 


.ASCII 


«DEF= 





Explanation 

Acceptable , but 
recommended procedure. 



not 



;DEF; is treated as a comment 
and ignored. 



Acceptable, but 
recommended procedure. 



not 



The assignment .ASCII=DEF is 
performed and an error 
generated upon encountering 
the second =. 



5.5.3.5 .ASCIZ - The .ASCIZ directive is equivalent to the .ASCII 
directive with a zero byte automatically inserted as the final 
character of the string. For example: 

when a list or text string has been created with a 
.ASCIZ directive, a search for the null character 
can determine the end of the list as follows: 

CRpIS 

LF«12 



MOV *HEIL0,PJ 
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XI 



MOV 
MQVB 



BNE X 



#LINBUF,R2 
CRl)*# CRZ)* 



JMOVE A CHARACTER Of THE 
/MESSAGE STRING INTO THE 
/OUTPUT BUFFER 
IBRANCH BACK IF BVTE 
INOT EQUAL TO 



HELLQJ .ASCIZ <CR>«IF>/MACRQ-1 1 V001 A/«CR>«IF» 

/INTRQ MESSAGE 



5.5.3.6 . RAD50 - The .RAD50 directive allows the user the capability 
to handle symbols in Radix-50 coded form (this form is sometimes 
referred to as MOD40 and is used in PDP-11 system programs) . Radix-50 
form allows three characters to be packed into sixteen bits; 
therefore, any 6-character symbol can be held in two words. The form 
of the directive is: 



where : 



.RAD50 
/ / 

string 



/string/ 



delimiters can be any printing 
characters other than the =, <, and ; 
characters . 

is a list of the characters to be 
converted (three characters per word) 
and may consist of the characters A 
through Z, through 9, dollar ($), dot 
(.) and space ( ) . If there are fewer 
than three characters (or if the last 
set is fewer than three characters) they 
are considered to be left justified and 
trailing spaces are assumed. Illegal 
nonprinting characters are replaced with 
a ? character and cause an I error flag 
to be set. Illegal printing characters 
set the Q error flag. 

The trailing delimiter may be a carriage return, semicolon, or 
matching delimiter. (A warning code is printed if it is not a 
matching delimiter, however.) For example: 



/PACK ABC INTO ONE WORD 

/PACK AB (SPACE) INTO ONE WORD. 

;PACK THREE SPACES INTO ONE WORD 

/PACK ABC INTO FIRST WORD AND 

;D (SPACE) CSPACE) INTO SECOND WORD 



A***** A 








219 00040 


003223 


.RAD50 


/ABC 


21 








22 00012 


003220 


.RAO50 


/AB/ 


23 00044 


000000 


.RAD50 


// 


24 00046 


003223 


.RAO50 


/ABCO/ 


0005(9 


014400 







Each character is translated into its Radix-50 equivalent 
indicated: 



as 
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Character 



Radix-50 
Equivalent (octal) 



ASCII (octal) 



(space) 





40 


A-Z 


1-32 


101-132 


$ 


33 


44 


* 


34 


56 


undefined 


35 


undefined 


0-9 


36-47 


60-71 



Note that another character could be defined for code 35, which is 
currently unused. 

The Radix-50 equivalents for three characters (C1,C2,C3) are combined 
in one 16-bit word as follows s 

Radix-50 value - ( (Cl*50) +C2) *50+C3 
For example: 

Radix-50 value of ABC is ( (1*50) +2) *50+3 or 3223 

See Appendix E for a table to quickly determine Radix-50 equivalents. 

Use of angle brackets is encouraged in the .ASCII, .ASCIZ, and .RAD50 
statements whenever leaving the text string to insert special codes. 
For example: 

.ASCII «101» ^EQUIVALENT TO .ASCII/A/ 

.RAD50 /AB/<35>f STORES 3255 IN NEXT WORD. 

CHR1M 
CHR2«2 
CHR3«i 



.RAO50 <CHRl»«CHR2s>«CHR3» 



^EQUIVALENT TO RAO50/ABC/ 



5.5.4 Radix Control 



5.5.4.1 .RADIX 

Numbers used in a MACRO source program are initially considered to be 
octal numbers. However, the programmer has the option of declaring 
the following radices: 

2, 4, 8, 10 

This is done via the .RADIX directive of the form: 

.RADIX n 
where n is one of the acceptable radices. 
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The argument to the .RADIX directive is always interpreted in decimal 
radix. Following any radix directive, that radix is the assumed base 
for any number specified until the following .RADIX directive. 

The default radix at the start of each program, and the argument 
assumed if none is specified, is 8 (octal). For example: 

.RADIX 10 IBESINS SECTION OP CODE WITH 

IDECIMAL RADIX 



f , ADn IHEVERTS TO OCTAC RAOIX 

In general it is recommended that macro definitions not contain or 
rely on radix settings from the .RADIX directive. The temporary radix 
control characters should be used within a macro definition. (tD, to, 
and tD are described in the following section. ) A given radix is valid 
throughout a program until changed. Where a possible conflict exists 
within a macro definition or in possible future uses of that code 
module, it is suggested that the user specify values using the 
temporary radix controls. 



5.5.4.2 Temporary Radix Control: tD, to, and tB - Once the user has 
specified a radix for a section of code, or has determined to use the 
default octal radix, he may discover a number of cases where an 
alternate radix is more convenient (particularly within macro 
definitions). For example, the creation of a mask word might best be 
done in the binary radix. 

MACRO has three unary operators to provide a single interpretation in 
a given radix within another radix as follows: 

tDx (x is treated as being in decimal radix) 
tOx (x is treated as being in octal radix) 
tBx (x is treated as being in binary radix) 

For example: 

tD123 

to 47 

tB 00001101 

tO<A+3> 

Notice that while the uparrow and radix specification characters may 
not be separated, the radix operator can be physically separated from 
the number by spaces or tabs for formatting purposes, where a term or 
expression is to be interpreted in another radix, it should be 
enclosed in angle brackets. 

These numeric quantities may be used any place where a numeric value 
is legal. 

A temporary radix change from octal to decimal may be made by 
specifying a decimal radix number with a "decimal point". For example: 
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100. 

1376. 

128. 



(144(8)) 

(2540(8)) 

(200(8)) 



5.5.5 Location Counter Control 

The four directives that control movement of the location counter are 
.EVEN and .ODD which move the counter a maximum of one byte, and .BLKB 
and .BLKW which allow the user to specify blocks of a given number of 
bytes or words to be skipped in the assembly. 



5.5.5.1 .EVEN - The .EVEN directive ensures that the assembly 
location counter contains an even memory address by adding one if the 
current address is odd. If the assembly location counter is even, no 
action is taken. Any operands following a .EVEN directive are 
ignored. 

The .EVEN directive is used as follows: 



.ASCIZ /THIS 18 * TEST/ 
• EVEN 

.WORD XYZ 



IA8SURES NEXT STATEMENT 
IBE5INS ON A *0KD BOUNDARY 



5.5.5.2 .ODD - The .ODD directive ensures that the assembly location 
counter is odd by adding one if it is even. For example: 

ICODE TO MOVE D*TA FROM AN INPUT LINE 
IT0 A BUFFER 



BUFFI 



AGAINI 



N»5 



000 

BYTE N*2 
BLKW N 



IBUPFER HAS 5 WORDS 



»C0UNT»2N BYTES 

IRESERVE BUFFER OF N WORDS 



MOV #SUFF,R2 IAD0RESS OF EMPTY BUFFER IN 9i 

MOV #LINE,R1 JADDRESS OF INPUT LINE IS IN Rl 

MOVB •1(R2),R0 |GET COUNT STORED IN BUFF-1 IN R0 

M0VB (RiJ+»(»2)+ JM0VE BYTE FROM LINE INTO BUFFER 

SEQ DONE MAS NULL CHARACTER SEEN? 

DEC R0 (DECREMENT COUNT 

BNE AGAIN |N0T»B, GET NEXT CHARACTER 



D0NEI 



CLRB 



(R2) I0UT OF ROOM IN BUFFER, CLEAR LAST 
IW0RD 



LINEI .ASCIZ /TEXT/ 
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In this case, .ODD is used to place the buffer byte count in the byte 
preceding the buffer, as follows: 



COUNT 


W/////////////M 



















BUFF-2 
BUFF 



5.5.5.3 .BLKB and .BLKW - Blocks of storage can be reserved using 
the .BLKB and .BLKW directives. .BLKB is used to reserve byte blocks 
and .BLKW reserves word blocks. The two directives are of the form: 



.BLKB 
.BLKW 



exp 
exp 



where exp is the number of bytes or words to reserve. If no argument 
is present, 1 is the assumed default value. Any legal expression 
which is completely defined at assembly time and produces an absolute 
number is legal. For example: 



2 

3 


t 






it 


000000' 


.CSECT 


5 0013000 

b 

7 000002 


pass: 


.BLKW 




SYMBOL! 


.BLKW 


2 


8 00000b 


MODEl 






1 00000b 


FLAGSI 


.BLKB 


1 


10 00007 


SECTOR! 


.BLKB 


1 


It 00010 


VALUE! 


.BLKW 


1 


12 0001c! 


HELLVLi 


.BLKW 


1 


13 




,-BLKW 


2 


14 00020 


CLCNAM! 


.BLKW 


2 


15 00024 


CLCFGSJ 


.BLKB 


1 


lb 00025 


CLCSECl 


.BLKB 


1 


17 0002b 


CLCLOC! 


.BLKW 


1 


16 00030 


CLCMAXI 


.BLKW 


1 


19 


000001 ' 


• END 





IMPURE 



INEXT GROUP MUST STAY TOGETHER 
»SYMB0L ACCUMULATOR 

JFLAG BITS 

ISYMBOL/EXPRESSION TYPE 
/EXPRESSION VALUE 

JEND OF GROUPED DATA 
JCURRENT LOCATION COUNTER 



The .BLKB directive has the same effect as: 

.=.+exp 
but is easier to interpret in the context of source code. 

5.5.6 Numeric Control 

Several directives are available to provide software complements to 
the floating-point hardware on the PDP-11. 
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A floating-point number is represented by a string of decimal digits. 
The string (which can be a single digit in length) may optionally 
contain a decimal point, and may be followed by an optional exponent 
indicator in the form of the letter E and a signed decimal exponent. 
The list of number representations below contains seven distinct, 
valid representations of the same floating-point numbers 

3 

3. 

3.0 

3.0E0 

3E0 

.3E1 

300E-2 

As can be quickly inferred, the list could be extended indefinitely 
(e.g., 3000E-3, .03E2, etc.). A leading plus sign is ignored (e.g., 
+3.0 is considered to be 3.0). Leading minus signs complement the sign 
bit. No other operators are allowed (e.g., 3.0+N is illegal). 

Floating-point number representations are valid only in the contexts 
described in the remainder of this section. 

Floating-point numbers are normally rounded. That is, when a 
floating-point number exceeds the limits of the field in which it is 
to be stored, the high-order excess bit is added to the low-order 
retained bit. For example, if the number were to be stored in a 
2-word field, but more than 32 bits were needed for its value, the 
highest bit carried out of the field would be added to the least 
significant position. In order to enable floating-point truncation, 
the .ENABL FPT directive is used and .DSABL FPT is used to return to 
floating-point rounding. 



5.5.6.1 .FLT2 and .FLT4 - Like the .WORD directive, the two 
floating-point storage directives cause their arguments to be stored 
in-line with the source program (have no effect in ASEMBL) . These two 
directives are of the formi 

.FLT2 argl,arg2,. . . 
.FLT4 argl,arg2,... 

where argl,arg2, etc. represent one or more floating point numbers 
separated by commas. 

.FLT2 causes two words of storage to be generated for each argument 
while .FLT4 generates four words of storage. 
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The following code shows the use of the .FLT4 directive: 



1 
2 
3 

« 0(90000 037314 
000002 1 at>3 1 it 
000004 146314 
00000b 14631b 

5 000010 036443 
000012 153412 
000014 036560 
000016 121727 

6 000020 034721 
000022 133427 
000024 054342 
000026 014545 

7 000030 031453 
000032 146167 
000034 010604 
000036 060717 

6 000040 022746 
000042 112624 
000044 137304 
000046 046741 

9 000050 005517 
0001052 130436 
000054 126505 
000056 034625 



AT0FT8I .FLT4 l.E-1 I10"-1 



.PLTfl l.E-2 I10-..2 



,FLT4 l.E-4 I10--4 



.FLT4 l.E-8 I10--8 



.FLT4 i.E-16 I10--16 



.FLT4 l.E-32 M0*"32 



5.5.6.2 Temporary Numeric Control: tF and tC - Like the temporary 
radix control operators, operators are available to specify either a 
1-word floating-point number (tF— not available in ASEMBL) or the 
one • s complement of a 1-word number ( tC) . For example : 



FL3.7: 



tF3.7 



creates a 1-word floating-point number at 
the value 3.7 as follows: 



location FL3.7 containing 



SIGN 
BIT 



s 


EXPONENT 


MANTISSA 



This 1-word floating-point number is the first word of the 2- or 

4-word floating-point number format shown in the PDP-11 Processor 
Handbook , and the statement: 



CMP 151: tCl51 

stores the one's complement of 151 
current radix is octal) as follows: 



in the current radix (assume 
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177626 



Since these control operators are unary operators, their arguments may 
be integer constants or symbols, and the operators may be expressed 
successively. For example: 

tCtD25 or tC31 or 177746 

The term created by the unary operator and its argument is then a term 
which can be used by itself or in an expression. For example: 

tC2+6 

is equivalent to: 

<tC2>+6 or 177775+6 or 000003 

For this reason, the use of angle brackets is advised. Expressions 
used as terms or arguments of a unary operator must be explicitly 
grouped. 

An example of the importance of ordering with respect to unary 
operators is shown below: 



tFl.O 


» 040200 


tF-1.0 


=■ 140200 


-tFl.O 


= 137600 


-tF-1.0 


- 037600 



The argument to the tF operator must not be an expression and should 
be of the same format as arguments to the .FLT2 and .FLT4 directives. 



5.5.7 Terminating Directives 



5.5.7.1 .END - The .END directive indicates the physical end of the 
source program. The .END directive is of the form: 

.END exp 

where exp is an optional argument which, if present, indicates the 
program entry point, i.e., the transfer address. 



5-50 



MACRO Assembler 

When the load module is loaded, program execution begins at the 
transfer address indicated by the .END directive. In a runtime system 
(the load module output of the Linker) a .END exp statement should 
terminate the first object module and .END statements should terminate 
any other object modules. 



5.5.7.2 .EOT - Under the RT-11 System, the .EOT directive is 
ignored. The physical end file allows several physically separate 
tapes to be assembled as one program. 



5.5.8 Program Boundaries Directive: .LIMIT 

The .LIMIT directive reserves two words into which the Linker puts the 
low and high addresses of the load module's relocatable code (the load 
module is the result of the link) . The low address (inserted into the 
first word) is the address of the first byte of code. The high 
address is the address of the first free byte following the relocated 
code. These addresses are always even since all relocatable sections 
are loaded at even addresses. (If a relocatable section consists of 
an odd number of bytes, the Linker adds one to the size to make it 
even.) 



5.5.9 Program Section Directives 

The assembler provides for 255(10) program sections: an absolute 
section declared by .ASECT, an unnamed relocatable program section 
declared by .CSECT, and 253(10) named relocatable program sections 
declared by .CSECT symbol, where symbol is any legal symbolic name. 
These directives allow the user to: 

1. Create his program (object module) in sections: 

The assembler maintains separate location counters for each 
section. This allows the user to write statements which are 
not physically contiguous but will be loaded contiguously. 
The following examples will clarify this: 
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.CSECT 


Al 


a 


81 


a 


CI 


z 


9TI 


CLR A 




CLR B 




CUR C 




.A SECT 




,«« 




.MONO ,«2iHALT 




.CSECT 




INC A 




BR 8T 




.END 



{START THE UNNAMED RELOCATABLE SECTION 

{ASSEMBLED AT RELOCATABLE 9, 

{RELOCATABLE 2 AND 

{RELOCATABLE U 

{ASSEMBLE CODE AT 

RELOCATABLE ADDRESS 

16 THROUGH 21 

{START THE ABSOLUTE SECTION 

{ASSEMBLE CODE AT 

{ABSOLUTE 4 THROUGH 7 

{RESUME THE UNNAMED RELOCATABLE 

{SECTION 

{ASSEMBLE CODE AT 

{RELOCATABLE £2 THROUGH 27 



The first appearance of .CSECT or .ASECT assumes the location 
counter is at relocatable or absolute zero, respectively. 
The scope of each directive extends until a directive to the 
contrary is given. Further occurrences of the same .CSECT or 
.ASECT resume assembling where the section was left off. 

.CSECT COM! {DECLARE SECTION C0M1 

Al {ASSEMBLED AT RELOCATABLE 

Bl {ASSEMBLED AT RELOCATABLE 2 

CI {ASSEMBLED AT RELOCATABLE « 

.CSECT COM2 {DECLARE SECTION COM2 

XI {ASSEMBLEO AT RELOCATABLE 

Yl {ASSEMBLED AT RELOCATABLE 2 

.CSECT C0M1 {RETURN TO COMt 

01 {ASSEMBLED AT RELOCATABLE 6 

.END 

The assembler automatically begins assembling at relocatable 
zero of the unnamed .CSECT if not instructed otherwise; that 
is, the first statement of an assembly is an implied .CSECT. 

All labels in an absolute section are absolute; all labels 
in a relocatable section are relocatable. The location 
counter symbol, ".", is relocatable or absolute when 
referenced in a relocatable or absolute section, 
respectively. Undefined internal symbols are assigned the 
value of relocatable or absolute zero in a relocatable or 
absolute section, respectively. Any labels appearing on a 
.ASECT or .CSECT statement are assigned the value of the 
location counter before the .ASECT or .CSECT takes effect. 
Thus, if the first statement of a program is: 

Al .ASECT 

then A is assigned to relocatable zero and is associated with 
the unnamed relocatable section (because the assembler 
implicitly begins assembly in the unnamed relocatable 
section) . 

Since it is not known at assembly time where the program 
sections are to be loaded, all references between sections in 
a single assembly are translated by the assembler to 
references relative to the base of that section. The 
assembler provides the Linker with the necessary information 
to resolve the linkage. Note that this is not necessary when 
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making a reference to an absolute section (the assembler 
knows all load addresses of an absolute section) . 

Examples : 

, ASECT 
••1000 

A» CC» X MSSEMBLED A9 CLR BASE OF UNNAMED 

RELOCATABLE SECTION *12 
JMP Y /ASSEMBLED A3 JMP BASE OP UNNAMED 

/RELOCATABLE SECTION ♦ 10 

•CSECT 

MOV R0,R1 

JMP A IA3SEMBLE0 AS JMP 1000 

VI HALT 
XI 

.END 

In the above example the references to X and Y were 
translated into references relative to the base of the 
unnamed relocatable section. 

2. Share code and/or data between object modules (separate 
assemblies) : 

Named relocatable program sections operate as FORTRAN labeled 
COMMON; that is, sections of the same name from different 
assemblies are all loaded at the same location by LINK. The 
unnamed relocatable section is the exception to this as all 
unnamed relocatable sections are loaded in unique areas by 
LINK. 

Note that there is no conflict between internal symbolic 
names and program section names; that is, it is legal to use 
the same symbolic name for both purposes. In fact, 
considering FORTRAN again, this is necessary to accommodate 
the FORTRAN statement: 

COMMON /X/A,B,C,X 

where the symbol X represents the base of this program 
section and also the fourth element of this program section. 

Program section names should not duplicate .GLOBL names. In 
FORTRAN language, COMMON block names and SUBROUTINE names 
should not be the same. 



The .ASECT and .CSECT program section directives are provided in MACRO 
to allow the user to specify an unnamed absolute or relocatable 
section. These directives are formatted as follows: 

.ASECT 
.CSECT 
.CSECT symbol 
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The single absolute section can be declared with an: 
.ASECT 

directive. No name can be associated with the absolute section 
specified by means of the .ASECT directive. The single unnamed 
relocatable program section can be declared with a: 

.CSECT 

directive. 

All named relocatable sections are loaded in unique areas by LINK. Up 
to 253(10) named relocatable program sections can be declared with: 

.CSECT symbol 

directives, where symbol is any legal symbolic name. 

The assembler automatically begins assembling at relocatable zero of 
the unnamed .CSECT if not instructed otherwise; that is, the first 
statement of an assembly is an implied .CSECT. 



5.5.10 Symbol Control: .GLOBL 

If a program is created in segments which are assembled separately, 
global symbols are used to allow reference to one symbol by the 
different segments. 

A global symbol must be declared in a .GLOBL directive. The form of 
the .GLOBL directive is: 

.GLOBL syml,sym2, . . . 

where : 

syml,sym2, etc. are legal symbolic names, separated by 

commas, tabs, or spaces where more than 
one symbol is specified. 

Symbols appearing in a .GLOBL directive are either defined within the 
current program or are external symbols, in which case they are 
defined in another program which is to be linked with the current 
program, by LINK, prior to execution. 

A .GLOBL directive line may contain a label in the label field and 
comments in the comment field. 

JDEMNE * SUBROUTINE WITH 2 ENTRY POINTS WHICH 
KALLS AN EXTERNAL SUBROUTINE 

.CSECT IDECLARE THE CONTROL SECTION 

.GLOBL A,B,C DECLARE A,B,C AS GL0BAL8 

*» M 0V »(R5)*,R0 IENTRY A IS DEFINED 

HQV *X,R! 

*» JS« PC,C ICALL EXTERNAL SUBROUTINE C 

"TS RS »EXIT 

■» MOV •{RS)*,R1 fDEFINE ENTRY B 

CLR Rl 

BR X 
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In the previous example, A and B are entry symbols (entry points), c 
xs an external symbol and X is an internal symbol. 

? itZiH ? ymb °i iS d ?? ined onl y w hen it appears in a .GLOBL directive. 
A symbol is not considered a global symbol if it is assigned the value 
of a global expression in a direct assignment statement. 

fnS^^ t0 externa l symbols can appear in the operand field of an 
instruction or assembler directive in the form of a direct reference, 

CUR EXT 
,WQRD |XT 
CUR •EXT 

or a direct reference plus or minus a constant, i.e.: 

Otb 

CUR EXT*0 

,W0R0 EXT. 2 

CUR »EXT*0 

A global symbol defined within the program can be used in the evalua- 
tion of a direct assignment statement, but an external symbol cannot. 
Since MACRO determines at the end of pass 1 whether a given global sym- 
bol is defined within the program or is expected to be external, a con- 
struction such as the following will cause errors at link time: 

. GLOBL FREE 
. GLOBL LIMITS 
FREE=LIMITS+2 7 FREE WILL NOT BE 

; DEFINED UNTIL PASS 2 



LIMITS: .LIMIT 



FREE will be flagged as an undefined global at link time. To allow 
correct linking, define FREE after LIMITS:. 

5.5.11 Conditional Assembly Directives 

Conditional assembly directives provide the programmer with the 
capability to conditionally include or ignore blocks of source code in 
the assembly process. This technique is used extensively to allow 
several variations of a program to be generated from the source 
program. 

The general form of a conditional block is as follows: 

.IF cond, argument (s) ; START CONDITIONAL BLOCK 

/STATEMENTS IN RANGE OF 
; CONDITIONAL 
; BLOCK 

•ENDC ;END CONDITIONAL BLOCK 

where i cond is a condition which must be met if the block is 

to be included in the assembly. These conditions 
are defined below. 
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argument (s) are a function of the condition to be tested. If 
more than one argument is specified, they must be 
separated by commas. 



range 



is the body of code which is included in the 
assembly or ignored depending upon whether the 
condition is met. 



The following are the allowable conditions: 



Conditions 
Positive Complement 


Arguments 


EQ 


NE 


expression 


GT 


LE 


expression 


LT 


GE 


expression 


DF 


NDF 


symbolic 
argument 


B 


NB 


macro-type 
argument 



IDN 

Z 
G 
L 



DIF 



NZ 



two macro- type 



Assembl e Block If 

expression=0 (or^O) 

expression>0 (or^O) 

expression<0 (or^O) 

symbol is defined 
(or undefined) 

argument is blank 
(or nonblank) 

arguments identical 



arguments separated (or different) 
by a comma 



expression 
expression 
expression 



same as EQ/NE 
same as GT/LE 
same as LT/GE 



IF DIF and IF IDN are not available in ASEMBL. 



For example: 

Ai.PHAi.1 



NOTE 

A macro-type argument is enclosed in 
angle brackets or within an up-arrow 
construction (as described in Section 
5.2.1.1). For example: 

<A,B / C> 
t/124/ 



.IF EQ,AlPMA*l 
.ENDC 



IA53EMBLE IF ALPHA*t«0 



Within the conditions DF and NDF the following two operators are 
allowed to group symbolic arguments: 



logical AND operator 

logical inclusive OR operator 
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For example: 



,IF DF,$VMt I SYM2 fASSEMiLI IF BOTH SYMl 

IAN0 8YM2 ARE DEFINED 

.ENOC 



5.5.11.1 Subconditionals - Subconditionals may be placed within 
conditional blocks to indicate: 

1. assembly of an alternate body of code when the condition of 
the block indicates that the code within the block is not to 
be assembled, 

2. assembly of a non-contiguous body of code within the 
conditional block depending upon the result of the 
conditional test to enter the block, 

3. unconditional assembly of a body of code within a conditional 
block. 

There are three subconditional directives, as follows: 
Su bconditional Function 

.IFF The code following this statement up to the next 
subconditional or end of the conditional block is 
included in the program if the value of the 
condition tested upon entering the conditional 
block is false. 

,IFT The code following this statement up to the next 
subconditional or end of the conditional block is 
included in the program if the value of the 
condition tested upon entering the conditional 
block is true. 

.IFTF The code following this statement up to the next 
subconditional or the end of the conditional block 
is included in the program regardless of the value 
of the condition tested upon entering the 
conditional block. 

The implied argument of the subconditionals is the value of the 
condition upon entering the conditional block. Subconditionals are 
used within outer level conditional blocks. Subconditionals are 
ignored within nested, unsatisfied conditional blocks. 

For example: 
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.IF 0P,SYM MSSEMBLE BLOCK XF SYM 18 DEFINED 
.IFF IA5SEMBLE THE FOLLOWING CODE ONLY XF 

ISYM IS UNDEFINED 



,IFT IA53EMBLE THE FOLLOWING CODE ONLY IF 

I3YM IS OEFINEO 

* 

.IFTF MS5EMBLE THE FOLLOWING CODE 

UNCONDITIONALLY 



However , 



.ENOC 



,IF DF,X IASSIMBLY TESTS FALSE 

.IF OF,Y ITESTS FALSE 

.IFF INESTEO CONDITIONAL 

fIGNOREO WITHIN NESTED. UNSATISFIED 
' ^CONDITIONAL BLOCK 



,IFT INOT SEEN 



.ENOC 
.ENOC 



.IF DF,X ITESTS TRUE 
.IF DF,Y ITESTS FALSE 

.IFF IIS ASSEMBLED 

IOUTER CONDITIONAL SATISFIED. 



,IFT INOT ASSEMBLED 



.ENOC 
.ENOC 



5.5.11.2 Immediate Conditionals - An immediate conditional directive 
is a means of writing a 1-line conditional block. In this form, no 
.ENDC statement is required and the condition is completely expressed 
on the line containing the conditional directive. Immediate 
conditions are of the form: 

. IIF cond, arg, statement 

where: cond is one of the legal conditions defined for 

conditional blocks in Section 5.5.11. 
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arg is the argument associated with the conditional 
specified, that is, either an expression, symbol, 
or macro-type argument, as described in Section 
5.5.11. 

statement is the statement to be executed if the condition 
is met. 

For example: 

.IXF DF,F00,BEQ ALPHA 
This statement generates the code: 

8E0 AL.PHA 
if che symbol F00 is defined. 

A label must not be placed in the label field of the .IIF statement. 
Any necessary labels may be placed on the previous line, as in the 
following example: 

LABEL I 

•IIF DF,FPP BEO ALPHA 

or included as part of the conditional statement: 

.IIF DF.FOO LABELI BEO ALPHA 



5.5.11.3 PAL-11R and PAL-11S Conditional Assembly Directives - In 
order to maintain compatibility with programs developed under PAL-llR 
and PAL-11S, the following conditionals remain permissible under 
MACRO. It is advisable that future programs be developed using the 
format for MACRO conditional assembly directives. 



Directive 

.IFZ or .IFEQ 

•IFNZ or.IFNE 

.IFL or .IFLT 

.IFG or .IFGT 

.IFGE 

.IFLE 

.IFDF 

. IFNDF 



Arguments 

expression 
expression 
expression 
expression 
expression 
expression 
logical expression 
logical expression 



Assemble Block if 

express ion=0 

express ion^O 

expression<0 

expression >0 

expression=>0 

expression<=0 
expression is true (defined) 
expression is false (undefined) 



The rules governing the usage of these directives are now the same as 
for the MACRO conditional assembly directives previously described. 
Conditional assembly blocks must end with the .ENDC directive and are 
limited to a nesting depth of 16(10) levels (instead of the 127(10) 
levels allowed under PAL-llR) . 
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5.6 MACRO DIRECTIVES 

5.6.1 Macro Definition 

It is often convenient in assembly language programming to generate a 
recurring coding sequence with a single statement. In order to do 
this, the desired coding sequence is first defined with dummy 
arguments as a macro. Once a macro has been defined, a single 
statement calling the macro by name with a list of real arguments 
(replacing the corresponding dummy arguments in the definition) 
generates the correct sequence or expansion. 



5.6.1.1 .MACRO - The first statement of a macro definition must be a 
.MACRO directive (not available in ASEMBL) . The .MACRO directive is of 
the form : 

.MACRO name, dummy argument list 
where : 

name is the name of the macro. This name is any legal 
symbol. The name chosen may be used as a label 
elsewhere in the program. 

represents any legal separator (generally a comma 
or space) . 

dummy zero, one, or more legal symbols which may appear 
argument anywhere in the body of the macro definition, 
list even as a label. These symbols can be used 
elsewhere in the user program with no conflicts of 
definition. Where more than one dummy argument is 
used, they are separated by any legal separator 
(generally a comma) . 

A comment may follow the dummy argument list in a statement containing 
a .MACRO directive. For example: 

.MACHO ABS A,B >0CFINE MACRO ABS WITH TWO ARGUMENTS 

A label must not appear on a .MACRO statement. Labels are sometimes 
used on macro calls, but serve no function when attached to .MACRO 
statements. 



5.6.1.2 .ENDM - The final statement of every macro definition must 
be an .ENDM directive (not available in ASEMBL) of the form: 

.ENDM name 

where name is an optional argument and is the name of the macro being 
terminated by the statement. 

For example: 
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.ENDM (terminates the current macro definition) 

.ENDM ABS (terminates the definition of the macro ABS) 

If specified, the symbolic name in the .ENDM statement must correspond 
to that in the matching .MACRO statement. Otherwise the statement is 
flagged and processing continues. Specification of the macro name in 
the .ENDM statement permits the assembler to detect missing .ENDM 
statements or improperly nested macro definitions. 

The .ENDM statement may contain a comment field, but must not contain 
a label. 

An example of a macro definition is shown below: 

.MACRO TYPMSG M£$SGE ITYPE A MESSAGE 

JSR R5, TYPMSG 

.WORD MESSGE 
• ENDM 



5.6.1.3 .MEXIT - In order to implement alternate exit points from a 
macro (particularly nested macros) , the .MEXIT directive is provided. 
.MEXIT (not available in ASEMBL) terminates the current macro as 
though an .ENDM directive were encountered. Use of .MEXIT bypasses 
the complications of conditional nesting and alternate paths. For 
example : 

.MACRO ALTR N,A,B 

II 

.IF EQ,N ISTART CONDITIONAL BLOCK 

.MEXIT IEXIT FROM MACRO DURING CONDITIONAL 

JBLOCK 
,ENDC IEND CONDITIONAL BLOCK 

.ENOM INORMAL END OF MACRO 



In an assembly where N=0, the .MEXIT directive terminates the macro 
expansion. 

Where macros are nested, a .MEXIT causes an exit to the next higher 
level. A .MEXIT encountered outside a macro definition is flagged as 
an error. 



5.6.1.4 Macro Definition Formatting - A form feed character used as 
a line terminator in a macro source statement (or as the only 
character on a line) , causes a page eject when the source program is 
listed. Used within a macro definition, a form feed character also 
causes a page eject. A page eject is not performed, however, when the 
macro is invoked. 
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Used within a macro definition, the .PAGE directive is ignored, but a 
page eject is performed at invocation of that macro. 



5.6.2 Macro Calls 

A macro must be defined prior to its first reference. Macro calls are 
of the general form: 

labels name, real arguments 

where s label represents an optional statement label. 

name represents the name of the macro specified in the 
.MACRO directive preceding the macro definition. 

, represents any legal separator (comma, space, or 
tab) . No separator is necessary where there are no 
real arguments. (Refer to Section 5.2.1.1.) 

real arguments 

are those symbols, expressions, and values which 
replace the dummy arguments in the .MACRO 
statement. Where more than one argument is used, 
they are separated by any legal separator. 

Where a macro name is the same as a user label, the appearance of the 
symbol in the operation field designates a macro call, and the 
occurrence of the symbol in the operand field designates a label 
reference. For examples 

ABSI NOV •»0,R1 MBS IS USED AS A LABEL 

• 

BR ASS JABS IS CONSIDERED A LABEL 

a 

ABS #«.£NT,LAK »CALL MACSO w I' r H 3 ARGUMENTS 



Arguments to the macro call are treated as character strings whose 
usage is determined by the macro definition. 



5.6.3 Arguments to Macro Calls and Definitions 

Arguments within a macro definition or macro call are separated from 
other arguments by any of the separating characters described in 
Section 5.2.1.1. For examples 

.MACRO REN A,B,C JMACRO DEFINITION 



REN ALPHA, BETA, <Ci,C2> /MACRO CALL 
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Jna^ en SacKS COn ^ ain se Parating characters are enclosed In paired 
k?= t brackets - ^ up-arrow construction is provided to allow anale 
brackets to be passed as arguments. axxow angle 

For example: 

REN <M0V X, Y»,#««,WEV 

This call would cause the entire statement: 

MOV *,Y 

to replace all occurrences of the symbol A in the macro definition 
Real arguments within a macro call are considered to be character 

macrS g e S xp a ansi a on. treated " * B ^ U *«** Until their - in ^ 

as%olIowsT COnstruction could h ^e been used in the above macro call 

«eN -/MOV X,Y/,#44.WEV 

which is equivalent to: 

REN «*0V X, />,#«<», WEV 

Since spaces are ignored preceding an argument, they can be used to 
increase legibility of bracketed constructions. 

»v«:^:^ Ma °*° Nestin 9 ~ Macro nesting (nested macro calls) , where the 
expansion of one macro includes a call to another macro, causes on! 

ESel ^Thl d'Sf 3 / b «. rem °y? d *«» ^ argument with eacHI^ng 
level. The depth of nesting allowed is dependent upon the amount J 
memory space used by the program. To pas S P an argument conSniSa 
legal argument delimiters to nested macros, the ardent should hi 
shown S below.° ne "* ° f ^ bra ° ketS f ° r —-'level S nes^ngf £ 



R0»X0 
R1»X1 
X«i0 

.MACRO LfcVELl DUM1,DUM2 

LEVELS DUM1 

tEVELi 0UM2 
.ENQM 

.MACRO LEVELS 0UM3 

DUM3 

ADO #10, R0 

MOV R0,(R1)+ 

.ENOM 

A call to the LEVELl macro: 

LEVELi <«M0V X,R0>> # «<CLR R >» 
causes the following expansion: 
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MOV X,R0 

ADD #l0rRB 

MOV R0,tf»lJ* 

CIR *& 

ADO •10»R» 

MOV R0,(R1)* 



SfiSiLnT „of LfSS 1 -* oSltble -aero until the outar macro 
has been called and expanded. For example: 



.MACRO LVt *cB 

.macro Lva * 



,ENON 
.ENDN 

The LV2 macro cannot be called by name until after the first call to 
the LV1 macro. Likewise, any macro defined within the LV2 macro 
definition cannot be referenced directly until LV2 has been called. 

■5632 Special Characters - Arguments may include special characters 
without encasing the argument in a bracket construction if that 
argument does not contain spaces, tabs, semicolons, or commas. For 
example : 

.MACRO PUSH ARG 
MOV A.RS,-(SP) 

.ENDM 



PUSH X+3CX2) 
generates the following code: 

MOV X*3CX2)#-(3P) 

5.6.3.3 Numeric Arguments passed as Symbols - When Passing macro 
armaments, a useful capability is to pass a symbol which can Jo 
treated by the macro as a numeric string. An argument preceded by the 
una?v operator backslash (\) is treated as a number in the current 
raSx. T not available in ASEMBL.) The ASCII characters 
representing the number are inserted in the macro expansion? their 
Stioll £ def ined in context (see Section 5.6.3.6 for an explanation 
of single-quote usage). For example: 
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A'BI 



.MACRO 


CNT 


.WORD 




.ENDM 




C»0 




.MACRO 


INC 


CNT 


k, \» 


B*B + l 




.ENDM 





A,B 



i. B 



INC X,C 

The macro call would expand to: 

X0I .WORD 

A subsequent identical call to the same macro would generate: 

XII .WORD 

and so on for later calls. The two macros are necessary because the 

dummy value of B cannot be updated in the CNT macro. In the CNT 

macro, the number passed is treated as a string argument. (Where the 

value of the real argument is 0, a single character is passed to the 
macro expansion.) 

The number being passed can also be used to make source listings 
somewhat clearer. For example, versions of programs created through 
conditional assembly of a single source can identify themselves as 
follows s 

.MACRO I0T SYM IASSUME THAT THE SYMBOL ID TAKES 

.IDENT /SYM/ fON A UNIQUE 2 DIGIT VALUE FOR 

.ENDM IOT >EACH POSSIBLE CONDITIONAL 

IASSEMBLY OF THE PROGRAM 

.MACRO OUT ARG 

IOT 005A'ARG 
.ENOM 
• 

OUT MO JWHERE 005* IS THE UPDATE VERSION 

I0F THE PROGRAM AND ARG INDICATES 
fTHE CONDITIONAL ASSEMBLY VERSION 

The above macro call expands to: 

.IDENT /005AXX/ 

where XX is the conditional value of ID. 

Two macros are necessary since the text delimiting characters in the 
•IDENT statement would inhibit the concatenation of a dummy argument. 
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5.6.3.4 Number of Arguments - If more arguments appear in the macro 
call than in the macro definition, the excess arguments are ignored. 
If fewer arguments appear in the macro call than in the definition, 
missing arguments are assumed to be null (consist of no characters) . 
The conditional directives .IF B and .IF NB can be used within the 
macro to detect null arguments. 



A macro can be defined with no arguments. 



5.6.3.5 Automatically Created Symbols Within User-Defined Macros - 
MACRO can be made to create symbols of the form n$ where n is a 
| decimal integer number such that 64<=n<=127. Created symbols are al- 
ways local symbols between 64$ and 127$. Such local symbols are crea- 
ted by the assembler in numerical order, i.e.: 

64$ 
65$ 



126$ 
127$ 

Created symbols are particularly useful where a label is required in 
the expanded macro. Such a label must otherwise be explicitly stated 
as an argument with each macro call or the same label is generated 
with each expansion (resulting in a multiply-defined label) . Unless a 
label is referenced from outside the macro, there is no reason for the 
programmer to be concerned with that label. 

The range of these local symbols extends between two explicit labels. 
Each new explicit label causes a new local symbol block to be 
initialized. 

The macro processor creates a local symbol on each call of a macro 
whose definition contains a dummy argument preceded by the ? 
character. For example: 



Bi 



,MAC«0 
TST 
BEQ 
ADD 

.ENDM 



ALPHA 
A 
B 
#5, A 



A,?8 



Local symbols are generated only where the real argument of the macro 
call is either null or missing. If a real argument is specified in 
the macro call, the generation of a local symbol is inhibited and 
normal replacement is performed. Consider the following expansions of 
the macro ALPHA above. 



January 1976 
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Generate a local symbol for missing argument: 

ALPHA Xi 

T5T Xi 

BEG) MS 

ADD #5, XI 

MSI 
Do not generate a local symbol: 

ALPHA xa,XYZ 

TST X2 

BfcQ XYZ 

ADO *3,X2 

XYZ! 

These assembler-generated symbols are restricted to the first sixteen 
(decimal) arguments of a macro definition. 



5,6.3.6 Concatenation - The apostrophe or single quote character (') 
operates as a legal separating character in macro definitions. An * 
character which precedes and/or follows a dummy argument in a macro 
definition is removed, and the substitution of the real argument 
occurs at that point. For example: 

.MACRO DEF A,B,C 

A'BS .ASCIZ /Q/ 

.WORO "A" f e 
• ENDM 

When this macro is called: 

DEF X, Y,<MACR0-il> 

it expands as follows : * 

XYI .ASCIZ /MACRQ-U/ 

.WORD 'X«Y 

In the macro definition, the scan terminates upon finding the first ' 
character. Since A is a dummy argument, the * is removed. The scan 
resumes with B, notes B as another dummy argument and concatenates the 
two dummy arguments. The third dummy argument is noted as going into 
the operand of the .ASCIZ directive. On the next line (this example 
is for purely illustrative purposes) the argument to .WORD is seen as 
follows: The scan begins with a * character. Since it is neither 
preceded nor followed by a dummy argument, the ' character remains in 
the macro definition. The scan then encounters the second ' character 
which is followed by a dummy argument and is discarded. The scan of 
the argument A terminates upon encountering the second * which is also 
discarded since it follows a dummy argument. The next • character is 
neither preceded nor followed by a dummy argument and remains in the 
macro expansion. The last • character is followed by another dummy 
argument and is discarded. (Note that the five * characters were 
necessary to generate two • characters in the macro expansion.) 

Within nested macro definitions, multiple single quotes can be used, 
with one quote removed at each level of macro nesting. 
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5.6.4 .NARG, .NCHR, and .NTYPE 

These three directives allow the user to obtain the number of 
arguments in a macro call (.NARG), the number of characters in an 
argument (.NCHR), or the addressing mode of an argument (.NTYPE), 
(They are not available in ASEMBL.) Use of these directives permits 
selective modifications of a macro depending upon the nature of the 
arguments passed. 

The .NARG directive enables the macro being expanded to determine the 
number of arguments supplied in the macro call and is of the form: 

label: .NARG symbol 

where: label is an optional statement label 

symbol is any legal symbol which is equated to the number 
of arguments in the macro call currently being 
expanded. The symbol can be used by itself or in 
expressions. 

This directive can occur only within a macro definition. An example 
of the use of .NARG follows. 

.MACRO ARGS AJ,A2,A3,A« 

.NARG NUM 

.IF EO NUM-1 (IF A2, A3, Att WERE 

JNOT SPECIFIED 

.WORD Ai 

.IFF HF ALU A«GS *ERE GIVEN 

.WORD Al 

.ASCII /AS/ 

.WORD A3 

.ASCII /*«/ 
.ENDC 
.ENDM 

ARG5 ALPHA 

.WORD ALPHA generated 

ARGS ALPHA, BETA, GAMMA, DELTA 

,W0P0 ALPHA ^ , 

.A5CII /BETA/ generated 

.WORD GAMMA 
.ASCII /DELTA/ 

The .NCHR directive enables a program to determine the number of 
characters in a character string, and is of the form: 

label: .NCHR symbol, <character string> 

where: label is an optional statement label 

symbol is any legal symbol which is equated to the number 
of characters in the specified character string. 
The symbol is separated from the character string 
argument by any legal separator. 
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< character string> 

is a string of printing characters which should 
only be enclosed in angle brackets if it contains 
a legal separator. A semicolon also terminates 
the character string. 

This directive can occur anywhere in a MACRO program. For example: 

.MACRO CHARS a 

.NCHP NUM,A 

.ASCII /A/ 

.IF EQ NUMM MF THE STRING CONTAINS 

IAN EVEN NUMBER OF 

/CHARACTERS 
.WORO «1 

.IFF HF STRING LENGTH 15 ODD 

.BYTE »2 
.ENDC 
,EN0M 

For example, using the above definition, the code: 

CHARS ALPHA 

expands to: 

.ASCII /ALPHA/ 
.BYTE -2 

and 

CHARS BETA 
expands to: 

.ASCII /BETA/ 
.WORD -1 

The .NTYPE directive enables the macro being expanded to determine the 
addressing mode and register of any argument, and is of the form: 

label: .NTYPE symbol, arg 

where: label is an optional statement label 

symbol is any legal symbol, the low order 6-bits of which 
is equated to the 6-bit addressing mode of the 
argument. The symbol is separated from the 
argument by a legal separator. This symbol can be 
used by itself or in expressions. 

arg is any legal macro argument (dummy argument) as 
defined in Section 5.6.3. 

This directive can occur only within a macro definition. An example 
of .NTYPE usage in a macro definition is shown below: 
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.MACRO SAVE ARG 
.NTYPE SYM,ARG 



.IF 

MQV 

.IFF 

MOV 

.ENOC 

.ENDM 


EU,S-YM*70 
ARCTEMP 

#ARG,TEMP 


Using this definition, the code 


SAVE 


H2 


expands tot 




MOV 


#R2,TEMP 


and 




SAVE 


ALPHA 


expands to : 




MOV 


•ALPHA, TEMP 



IRE5ISTER MODE 
INON-HEGISTER MODE 



5.6.5 .ERROR and .PRINT 

The .ERROR directive (not available in ASEMBL) is used to output 

messages to the listing file during assembly pass 2. A common use is 

to provide diagnostic announcements of a rejected or erroneous macro 
call. The form of the .ERROR directive is as follows: 

label: .ERROR expr; text 

where: label is an optional statement label 

expr is an optional legal expression whose value is 
output to the listing file when the .ERROR 
directive is encountered. Where expr is not 
specified, the text only is output to the listing 
file. 

; denotes the beginning of the text string to be 
output. 

text is the string to be output to the listing file. 
The text string is terminated by a line 
terminator. 

Upon encountering a .ERROR directive anywhere in a MACRO program, the 
assembler outputs a single line containing: 

1. the sequence number of the .ERROR directive line, 

2. the current value of the location counter, 

3. the value of the expression if one is specified, and, 
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4. the text string specified. 

For example, assume the following error macro occurs: 

.MACRO STORE SRC0E5T 

.NTYPE A,DEST 

.IF EQ,<A«,7>*6 HF STACK POINTER USED 

a;unacceptable macro ARGUMENT 



.ERROR 




.IFF 




MOV 


SRCiDEST 


.ENDC 




.feNPM 





STORE R3,#<l(SP) 

and the following line is output; 

****** p 

00000 6)00076 .ERROR A , UNACCEPTABLE MACRO ARGUMENT 

This message is used to indicate an inability of the subject macro to 
cope with the argument DEST which is detected as being indexed 
deferred addressing mode (mode 70) with the stack pointer (%6) used as 
the index register. The line is flagged on the assembly listing with 
a P error code. 

The .PRINT directive is identical to .ERROR except that it is not 
flagged with a P error code. (.PRINT is not available in ASEMBL.) 



5.6.6 Indefinite Repeat Block: .IRP and .IRPC 

An indefinite repeat block (not available in ASEMBL) is a structure 
very similar to a macro definition. An indefinite repeat is 
essentially a macro definition which has only one dummy argument and 
is expanded once for every real argument supplied. An indefinite 
repeat block is coded in-line with its expansion rather than being 
referenced by name as a macro is referenced. An indefinite repeat 
block is of the form: 



label ; 



.IRP arg,<real arguments > 



(range of the indefinite repeat) 



.ENDM 

where: label is an optional statement label. A label may not 

appear on any .IRP statement within another macro 
definition, repeat range or indefinite repeat 
range, or on any .ENDM statement. 

arg is a dummy argument which is successively replaced 
with the real arguments in the .IRP statement. 
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<real arguments > 

is a list of arguments to be used in the expansion 
of the indefinite repeat range and enclosed in 
angle brackets. Each real argument is a string of 
zero or more characters or a list of real 
arguments (enclosed in angle brackets) . The real 
arguments are separated by commas. 

range is the code to be repeated once for each real 
argument in the list. The range may contain macro 
definitions, repeat blocks, or other indefinite 
repeat blocks. Note that only created symbols 
should be used as labels within an indefinite 
repeat range. 

An indefinite repeat block can occur either within or outside macro 
definitions, repeat ranges, or indefinite repeat ranges. The rules 
for creating an indefinite repeat block are the same as for the 
creation of a macro definition (for example, the .MEXIT statement is 
allowed in an indefinite repeat block). Indefinite repeat arguments 
follow the same rules as macro arguments. A second type of indefinite 
repeat block is available which handles character substitution rather 
than argument substitution. The .IRPC directive is used as follows: 

label: .IRPC arg, string 

(range of indefinite repeat) 



.ENDM 

On each iteration of the indefinite repeat range, the dummy argument 
(arg) assumes the value of each successive character in the string. 
Terminators for the string are: space, comma, tab, carriage return, 
line feed, and semicolon. 

Figure 5-6 is an example of .IRP and .IRPC usage. 

IRPTST RT-1 1 MACRO VM02-09 i 1 1 0ai49 PAGE t 

1 
i 
3 

u 

b .TITLE IRPTST 

7 .LIST MD,MC,ME 

8 000080 R0*X0 

9 000000 012700 *0V #TABLE.K0 

00005b' 
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10 








,IRP 


X,«A,B,C 


n 












12 








MOV 


X, CR«0* 


13 








.ENDM 






00004 


016720 

000032 




MOV 


A,(R0)+ 




00010 


016720 

000030 




MOV 


B, (R0)+ 




00014 


016720 

000026 




MOV 


C, CR0J + 




0002U 


016720 

000024 




MOV 


0. (R0)* 




00024 


016720 
000022 




MOV 


E, (R0)* 




00030 


016720 
000020 




MOV 


F, t«03* 


14 








.IRPC 


X, ABCDEF 


15 








.ASCII 


nt 


16 








.ENDM 






00034 


101 




.ASCII 


/A/ 




00035 


102 




.ASCII 


/B/ 




00036 


103 




.ASCII 


/C/ 




00037 


104 




.ASCII 


/D/ 




00040 


105 




.ASCII 


/E/ 




00041 


106 




.ASCII 


/F/ 


17 












Id 


00042 


041101 


a: 


.WORD 


"AB 


19 


00044 


041502 


b: 


.WORD 


Mac 


20 


0004b 


042103 


cj 


,WDRD 


"CD 


21 


00050 


042504 


ot 


.WORD 


"OE 


za 


00052 


043105 


El 


.WORD 


"EF 


a 


00054 


043506 


Fl 


.WORD 


"FG 


24 


00056 




TABLEI 


.6LKW 


6 


23 




000001 ' 




,ENO 





Figure 5-6 
,IRP and .IRPC Example 



5,6.7 Repeat Block: .REPT 

Occasionally it is useful to duplicate a block of code a number of 
times in line with other source code. (.REPT is not available in 
ASEMBL.) This is performed by creating a repeat block of the form: 



label: 



,REPT expr 



(range of repeat block) 
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.ENDM 



;OR .ENDR 



where : 



label is an optional statement label. The .ENDR or 
.ENDM directive may not have a label. A .REPT 
statement occurring within another repeat block, 
indefinite repeat block, or macro definition may 
not have a label associated with it. 

expr is any legal expression controlling the number of 
times the block of code is assembled. Where 
expr<0, the range of the repeat block is not 
assembled. 

range is the code to be repeated expr number of times. 
The range may contain macro definitions, 
indefinite repeat blocks, or other repeat blocks. 
Note that no statements within a repeat range can 
have a label. 

The last statement in a repeat block can be an .ENDM or .ENDR 
statement. The .ENDR statement is provided for compatibility with 
previous assemblers. 

The .MEXIT statement is also legal within the range of a repeat block. 



5.6.8 Macro Libraries: .MCALL 

All macro definitions must occur prior to their referencing within the 
user program. MACRO provides a selection mechanism for the programmer 
to indicate in advance those system macro definitions required by his 
program. 

The .MCALL directive is used to specify the names of all system macro 
definitions not defined in the current program but required by the 
program (not available in ASEMBL) . The .MCALL directive must appear 
before the first occurrence of a macro call for an externally defined 
macro. The .MCALL directive is of the form: 

.MCALL argl,arg2,.. . 

where argl,arg2, etc. are the names of the macro definitions required 
in the current program. 

When this directive is encountered, MACRO searches the system library 

file, SYSMAC.SML, to find the requested def inition(s) . MACRO searches 
for SYSMAC.SML on the system device (SY:). 

See Appendix D for a listing of the 
stored on the system device. 



system macro file (SYSMAC.SML) 



5.7 CALLING AND USING MACRO 

The MACRO Assembler assembles one or more ASCII source files 
containing MACRO statements into a single relocatable binary object 
file. Assembler output consists of this binary object file and an 
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optional assembly listing followed by the symbol table listing. CREF 
(Cross Reference) listings may also be specified as part of the 
assembly output by means of switch options, 

MACRO is executed using the RT-11 Monitor R command as follows: 
.R MACRO 

The assembler responds by typing an asterisk (*) to indicate readiness 
to accept command string input. In response to the * printed by the 
assembler, the user types the output file specification (s ) , followed 
by an equal sign or left angle bracket, followed by the input file 
specification (s) in a command line as follows: 



*dev:obj,dev:list/s:arg=dev:sourcel,..,dev:sourcen/s:arg 



where: 



dev: 

obj 

list 

sour eel, 

. . ,sourcen 

/s :arg 



is any legal RT-11 device for output; 
must be file-structured for input 

is the binary object file 

is the assembly listing file containing 
the assembly listing and symbol table 

are the ASCII source files containing 
the macro source program (s) j a maximum 
of six source files is allowed 
represents a switch and 
explained in Section 5.7.1 



argument as 



A null specification in either of the output file fields signifies 
that the associated output file is not desired. 

One or more switches can be indicated with the appropriate file 
specification to provide MACRO with information about that file. 

The default case for each file specification is noted below: 



file 


device 


filename 


extension 


object 


DK: 


.OBJ 


listing 


device used 
for object 
output 


— 


.LST 


sourcel 


DK: 


- 


.MAC 


source2 

• 
• 


device used 
for last source 
file specified 


.MAC 


sourcen 








system 

macro 

file 


system device 
SY: 


SYSMAC 


.SML 



Type CTRL C to halt MACRO at any time and return control to the 
monitor. To restart the assembler type R MACRO or the REENTER command 
in response to the monitor's dot. 
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NOTE 



If tC was typed while a CREF listing was 
being produced, the REENTER command may 
not be accepted. In this case, type R 
MACRO to restart the assembler. 



5.7.1 Switches 

There are three types of switch options: listing control switches, 
function switches, and CREF specification switches. The listing 
control switches (/L,/N) provide capabilities similar to those 
described in detail in section 5.5.1.1. The function control switches 
(/D,/E) provide function control as described in Section 5.5.2; 
arguments for these switches are summarized in Section 5.7.1.2. CREF 
control switches allow the user to obtain a detailed cross-referenced 
listing of his assembled file, and are described in detail in Section 
5.7.1.3. Multiple arguments may be specified for a particular switch, 
if desired, by separating each switch value from the next by a colon. 
For example: 

/N:TTM:CND 

These switches turn off teleprinter mode and suppress printing of 
unsatisfied conditionals (as described in the next section) . Also, the 
switches are not restricted to appearing near a particular file in the 
command string; /N:TTM, for example, is legal in all of the following 
places : 

* , LP : /N : TTM=source 
* , LP : =source/N : TTM 
*/N:TTM,LP:=source 

and they are all equivalent in function. 



5.7.1.1 Listing Control Switches - A listing control switch (/L for 
list or /N for nolist) is indicated in a command line as follows: 

*dev : ob j . ext ,dev : list . ext/s : arg=dev : source . ext 

where s:arg represents /L or /N; the remainder of the command line 
abbreviations are as described in Section 5.7. 

The /N switch with no argument causes only the symbol table, table of 
contents and error listings to be produced. The /L switch with no 
arguments causes .LIST and .NLIST directives that appear in the source 
program but have no arguments to be ignored. A summary of the argu- 
ments which are valid for the listing control switches follows (refer 
to Section 5.5.1.1 for details): 

Argument Default Controls listing of 

SEQ list Source line sequence numbers 

LOC list Location counter 

BIN list Generated binary code 

BEX list Binary extensions 
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SRC 


list 


COM 


list 


MD 


list 


MC 


list 


ME 


nolist 


MEB 


nolist 


CND 


list 


LD 


nolist 


TOC 


list 


TTM 


terminal mode 


SYM 


list 
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Source code 

Comments 

Macro definitions, repeat 

range expansions 
Macro calls, repeat range expansions 
Macro expansions 
Macro expansion binary code 
Unsatisfied conditionals, .IP and 

.ENDC statements 
Listing directives with no arguments 
Table of Contents 
Listing output format 
Symbol table 

For example, a command line in the following format allows binary code 
to be listed throughout the assembly using the 132-column line printer 
format : 

* , LP : /L : MEB/N : TTM=FILE 

5.7.1.2 Function Switches - The function control switches (/D for 
disable and /E for enable) are used to enable or disable certain 
functions in source input files and are indicated in the command line 
as follows : 

*dev : ob j . ext , dev : lis t . ext=dev : source/s : arg 

/s:arg here represents either /D:arg or /E:arg. A summary of the 
arguments which are valid for use with the function control switches 
follows (refer to Section 5.5.2 for details): 

Argu ment Default Enables or disables 

Absolute binary output 

Assembly of all absolute addresses 

as relative addresses 
Source columns 73 and greater to be 

treated as comments 
Floating point truncation 
Accepts lower case ASCII input 
Local symbol block 
Binary output 

For example, the following commands assemble a file allowing all 80 
columns of each card to be used as input (note that since MACRO is a 
two-pass assembler, the cards cannot be read directly from the card 
reader; input from any nonf ile-structured device must first be trans- 
ferred to a file-structured device before assembly) : 

, R PI P 

-» C fi R D 3 . f'i ni C - C R : f ' fl 

* ~C 

. R MSCRO 

* i L P : = C fi R D S . M fi C i E : C D R 

Use of either the function control or listing control switches and 
arguments at assembly-time will override any corresponding listing or 
function control directives and arguments in the source program. For 
example, assume the following appears in the source program: 

.NLIST MEB 

MACRO References 

.LIST MEB 
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ABS 

AMA 


disable 
disable 


CDR 


disable 


FPT 

LC 

LSB 

PNC 


disable 
disable 
disable 
enable 
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The "MEB" printing will be disabled for the block indicated; however, 
if /L:MEB is indicated in the assembly command line, both the .NLIST 
MEB and the .LIST MEB will be ignored and the "MEB" printing will be 
enabled everywhere in the program. 

5.7,1.3 Cross Reference Table Generation (CREF) - A cross reference 
table of all or a subset of all symbols used in the source program and 
the statements where they were defined or used can be obtained 
automatically following an assembly by specifying /C:arg with the 
assembly listing file specification (and any listing or function 
control specifications) as follows: 

*dev : ob j . ext , dev : lis t . ext/s : arg/C : arg=dev : source . ext 

/s:arg represents /L:arg, /N:arg, /E:arg, or /D:arg. (If the listing 
device is magtape or cassette, and a CREF listing is desired, the 
handler must first be loaded, using the monitor LOAD command . ) 

There are six sections to a complete cross reference listing: 

1. Cross reference of program symbols (i.e., labels used in the 
program and symbols used on the left of the "=" operator) . 

,2. Cross reference of register-equate symbols (those symbols 

which are defined in the program by a "SYMBOL=--%N", 0<=N<=7, 

construct. (Normally this consists of the symbols RO, Rl, 
R2, R3, R4, R5, SP, and PC.) 

3. Cross reference of MACRO symbols (names of macros as defined 
by a .MACRO directive, or as specified in a .MCALL 
directive) . 

4. Cross reference of permanent symbols (all operation mnemonics 
and assembler directives) . 

5. Cross reference of control sections (those names specified as 
the operand of a .CSECT directive, plus the blank .CSECT and 
the absolute section ". ABS." which are always defined by 
MACRO) . 

6. Cross reference of errors (all errors flagged on the listing 
are grouped by error type) . 

Any or all of the above sections may be included in the cross 
reference listing as desired. The associated switch options and their 
arguments are listed below: 

Switch 

Argument Section Type 

/C:S User-defined symbols 
/C:R Register symbols 
/C:M Macro symbolic names 
/C:P Permanent symbols 

( instructions , directives ) 
/C:C Control sections (.CSECT 

symbolic names) 
/C:E Error codes 
/C<no arg> Equivalent to /C:S:M:E 
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The specification of a /C switch in a command string causes a 
temporary file, "DK:CREF.TMP", to be generated. If device DK: is 
write-locked or contains insufficient free space for the temporary 
file, the user may allocate the temporary file on another device. To 
do so, a third output file specification is given in the MACRO command 
string; this file is then used instead of DK:CREF.TMP, and is purged 
after use. For example, a command string of this type: 

* , LP s , RK2 1 TEMP . TMP=SOURCE/C 

causes "RK2:TEMP.TMP" to be used as the temporary file. 

Figure 5-7 illustrates assembled source code and Figure 5-8 contains 
the CREF output. The command line used to produce these listings was: 

*,LPs/C:S:M:R:P:CsE/N:BEX=EXAMPL 

An explanation of the CREF output follows the figures. 
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Cross reference tables, if requested, are generated at the end of a 
MACRO assembly listing. Each table begins on a new page (the tables 
in Figure 5-8 have been consolidated due to space considerations) . 
Symbols, control sections, and error codes are listed at the left 
margin of the page; corresponding references are indicated next to 
them across the page from left to right. A reference is of the form 
p-1, where p is the page on which the symbol, control section, or 
error code appears, and 1 is the line number within the page. A 
number sign (#) appears next to a reference wherever a symbol has been 
defined. An asterisk appears next to a reference wherever a 
destructive reference has been made to the symbol (i.e., the contents 
of the location defined by that symbol has been altered at that 
point) . 

The CREF output requested in the preceding figures included user 
defined symbols, macro symbolic names, control sections, error codes, 
register symbols, and permanent symbols. Since no errors were 
generated in this assembly, no CREF output for error codes was 
produced. 



5.8 MACRO ERROR MESSAGES 

MACRO error messages enclosed in question marks are output on the 
terminal. The single-letter error codes are printed in the assembly 
listing. 

In terminal mode these error codes are printed following a field of 
six asterisk characters and on the line preceding the source line 
containing the error. For example: 

****** a 

26 00236 000002' .WORD REL1+REL2 

Error Code Meaning 

A Addressing error. An address within the instruction is 
incorrect. Also may indicate a relocation error. The 
addition of two relocatable symbols is flagged as an A 
error. May also indicate that a local symbol is being 
defined more than 128 words from the beginning of a 
local symbol block. 

B Bounding error. Instructions or word data would be 
assembled at an odd address in memory. The location 
counter is updated by +1. 

D Multiply-defined symbol referenced. Reference was made 
to a label (not a local label) that is defined more than 
once. 



E 

I 



End directive not found. (A .END is generated.) 

Illegal character detected. Illegal characters which 
are also non-printing are replaced by a ? on the 
listing. The character is then ignored. 



Line buffer overflow, i.e., input line greater than 132 
characters. Extra characters on a line are ignored in 
terminal mode. 
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M 

N 
O 
P 



Multiple definition of a label. A label was 
encountered which was equivalent (in the first six 
characters) to a previously encountered label. 

Number containing 8 or 9 has decimal point missing. 

Opcode error. Directive out of context. 

Phase error. A label's definition or value varies from 
one pass to another or a local symbol occurred twice 
within a local symbol block. 



Questionable syntax. There are missing arguments or 
the instruction scan was not completed or a carriage 
return was not immediately followed by a line feed or 
form feed. 

Register-type error. An invalid use of or reference to 
a register has been made. 

Truncation error. A number generated more than 16 bits 
of significance or an expression generated more than 8 
bits of significance during the use of the .BYTE 
directive. 



U 



Undefined symbol. An undefined symbol was encountered 

during the evaluation of an expression. Relative to 

the expression, the undefined symbol is assigned a 
value of zero. 



Instruction which is not compatible among all members 
of the PDP-11 family. 



Error Message 



?BAD SWITCH? 



Explanation 

The switch specified was 
recognized by the program. 



not 



7INSUFFICIENT CORE? 



?I/0 ERROR ON CHANNEL n? 



There are too many symbols in the 
program being assembled. Try 
dividing program into 
separately-assembled subprograms. 

A hardware error occurred while 
attempting to read from or write to 
the device on the channel specified 
in the message. (Channel numbers 
(0<»n<=10 octal) are assigned to 
files in the manner described in 
Section 9 . 4 . 7 , Chapter 9 . ) 

Note that the CREF temporary file 
is on channel 2 even if it was not 
specified in the command string 
(i.e., if the default file 
DK:CREF.TMP is used) . 



5-85 



January 1976 



MACRO Assembler 



?NO INPUT FILE? 



?OUTPUT DEVICE FULL? 



TOO MANY OUTPUT FILES 



No input file was specified and 
there must be at least one input 
file. 

No room to continue writing output 
Try to compress device with PIP. 

Too many output files were speci- 
fied. 



All CREF error messages begin with C- to distinguish them from MACRO 
error messages. "When a CREF error occurs, the error message is prin- 
ted on the console terminal and CREF chains back to MACRO; MACRO 
prints an asterisk, at which time another command line may be entered. 



Error Message 
?C-CHAIN-ONLY-CUSP? 



Explanation 

An attempt was made either to "R 
CREF" or to "START" a copy of CREF 
which was in memory. CREF can only 
be "chained" to. 



?C-CRF FILE ERROR? 



?C-DEVICE? 



An output error occurred while 
accessing "DK:CREF.TMP" , the tem- 
porary file passed to CREF. 

An invalid device was specified to 
CREF. 



7C-LST FILE ERROR? 



An output error occurred while 
attempting to write the cross- 
reference table to the listing file. 
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6 . 1 INTRODUCTION 

The RT-11 Linker converts object modules produced by either one of the 
RT-11 assemblers or FORTRAN IV into a format suitable for loading and 
execution. This allows the user to separately assemble a main program 
and each of its subroutines without assigning an absolute load address 
at assembly time. The object modules of the main program and 
subroutines are processed by the Linker to: 

1. Relocate each object module and assign absolute addresses 

2. Link the modules by correlating global symbols defined in one 
module and referenced in another module 

3. Create the initial control block for the linked program 

4. Create an overlay structure if specified and include the 
necessary run-time overlay handlers and tables 

5. Search user specified libraries to locate unresolved globals 

6. Optionally produce a load map showing the layout of the load 
module 

The RT-11 Linker requires two or three passes over the input modules. 
During the first pass it constructs the global symbol table, including 
all control section names and global symbols in the input modules. If 
library files are to be linked with input modules, an intermediate 
pass is needed to force the modules resolved from the library file 
into the root segment (that part of the program which is never 
overlaid). During the final pass, the Linker reads the object modules, 
performs most of the functions listed above, and produces a load 
module (.LDA for use with the Absolute Loader, save image (.SAV) for a 
Single-job system or for the background job of an P/B System, and 
relocatable (.REL) format for the foreground iob of an F/B System). 

The Linker runs in a minimal RT-11 system of 8K; any additional memory 
is used to facilitate efficient linking and to extend the symbol table. 
Input is accepted from any random-access device on the system; there 
must be at least one random-access device (disk or DECtape) for save 
image or relocatable format output. 
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6.2 CALLING AND USING THE LINKER 

To call the Linker, type the command: 

R LINK 

and the RETURN key in response to the Keyboard monitor's dot. The 
Linker prints an asterisk and awaits a command string. 

Type CTRL C to halt the Linker at any time and return control to the 
monitor. To restart the Linker, type R LINK or the REENTER command in 
response to the monitor's dot. The Linker outputs an extra line feed 
character when it is restarted with REENTER or after an error in the 
first command line. When the Linker is finished linking, control 
returns to the CSI automatically. An extra line feed character 
precedes the asterisk printed by the CSI. 



6.2.1 Command String 

The first command string entered in response to the Linker's asterisk 
has the following format: 

*dev:binout ,dev :mapout=dev :ob j 1 ,dev :ob j 2 , . . . /sl/s2/s3 
where : 

dev: is a random-access device for all files except 

dev::mapout, which can be any legal output de- 
vice. If dev: is not specified, DK is assumed., 
If the output is to be LDA format (that is, 
the /L switch was used) , the output file need 
not be on a random-access device. 

binout is the name to be assigned to the Linker's 
save image, LDA format, or REL format output 
file. This file is optional; if not 
specified, no binary output is produced. 
(Save image is the assumed output format 
unless the /L or /R switches are used.) 

mapout is the optional load map file. 

objl,... are files of one or more object modules to be 
input to the Linker (these may be library 
files) . 

/sl/s2/s3 are switches as explained in Table 6-1 and 
Section 6.8. 

If the /C switch is given, subsequent command lines may be entered as: 

*objm,objn,.../sl/s2 

The /C switch is necessary only if the command string will not fit on 
one line or if the overlay structure is used. If an error occurs in a 
continued command line (e.g., 7FILE NOT FND?) , only the line in error 
need be retyped. 
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If an output file is not specified, the Linker assumes that the 
associated output is not desired. For example, if the load module and 
load map are not specified, only error messages (if any) are printed 
by the Linker. 

The default values for each specification are: 

Device Filename Extension 



Load Module 
Map Output 



SAV, REL(/R), LDA(/L) 
MAP 

OBJ 



DK: none 

Same as none 

load module 
Object Module DK: or same none 
as previous 
object module 

If a syntax error is made in a command string, an error message is 
printed. A new command string can then be typed following the 
asterisk. 

If a nonexistent file is specified a fatal error occurs; control is 
returned to the command string interpreter, an asterisk is printed and 
a new command string may be entered. 



6.2.2 Switches 

The switches associated with the Linker are listed in Table 6-1. The 
letter representing each switch is always preceded by the slash 
character. Switches must appear on the line indicated if the command 
is continued on more than one line. They may be positioned anywhere 
on the line. (A more detailed explanation of each switch is provided 
in Section 6.8.) 

Table 6-1 
Linker Switches 



Switch 
Name 


Command 
Line 


Meaning 


/A 


1st 


Alphabetizes the entries in the load map. 


/B:n 


1st 


Bottom address of program is indicated as 
n (illegal for foreground links) . 


/c 


any 


Continues input specification on another 
command line. Used also with /0. 


/F 


1st 


Instructs the Linker to use the default 
FORTRAN library, FORLIB.OBJ; note that 
FORLIB does not have to be specified in 
the command line. 


/I 


1st 


Includes the global symbols to be 
searched from the library. 


/L 


1st 


Produces an output file in LDA format 
(illegal for foreground links). 



(Continued on next page) 
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Table 6-1 (Cont.) 
Linker Switches 



Switch 
Name 


Command 
Line 


Meaning 


/M or 
/Msn 


1st 


Stack address is to be specified at the 
terminal keyboard or via n. 


/Osn 


any but 
the 1st 


Indicates that the program will be an 
overlay structure; n specifies the 
overlay region to which the module is 
assigned. 


/R 


1st 


Produces output in REL format; only 
files in REL format will run in the 
foreground (REL format files may not be 
run under a Single-Job system) 


/s 


1st 


Allows the maximum amount of space in 
memory to be available for the Linker's 
symbol table. (This switch should only 
be used when a particular link stream 
causes a symbol table overflow. ) 


/T or 
/T:n 


1st 


Transfer address is to be specified at 
terminal keyboard or via n. 



6.3 ABSOLUTE AND RELOCATABLE PROGRAM SECTIONS 

A program produced by one of the RT-11 assemblers or FORTRAN IV can 
consist of an absolute program section, declared by the .ASECT 
assembler directive, and relocatable program sections declared by the 
.CSECT assembler directive. A .CSECT directive is assumed at the 
beginning of the source program. The instructions and data in 
relocatable sections are normally assigned locations beginning at 
1000 (octal) or for a foreground link. The assignment of addresses 
can be influenced by command string switches and the size of the 
absolute section (.ASECT, if present). Each control section is 
assigned a memory address; the Linker then appropriately modifies all 
instructions and/or data as necessary to account for the relocation of 
the control sections. 



NOTE 

Foreground programs cannot use .ASECTs 
beyond 1000 (octal) ; as a general 
practice, they should be avoided under a 
Foreground/Background system. 

The RT-11 Linker handles the absolute section as well as the named and 
unnamed control sections. The unnamed control section is internal to 
each object module. That is, every object module can have an unnamed 
control section but the Linker treats each control section 
independently. Each is assigned an absolute address such that it 
occupies an exclusive area of memory. Named control sections, on the 
other hand, are treated globally; if different object modules have 
control sections with the same name, they are all assigned the same 
absolute load address and the size of the area reserved for loading of 
the section is the size of the largest. Thus, named control sections 
allow for the sharing of data and/or instructions among object 
modules. This is the same as the handling and function of COMMON in 
FORTRAN IV. The names assigned to control sections are global and can 
be referenced as any other global symbol. 
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NOTE 

If relocatable code is to be linked for 
the foreground, no location may be filled 
more than once (using location counter 
arithmetic).; any such location may be 
improperly relocated during the FRUN and 
may cause program or system failure. 

For example, the following code illustrates 
a program using location counter arithmetic 
that is illegal if linked for the foreground. 
Note that the code at line 15 starts at due 
to location counter modification. To correct 
this program for foreground linking, remove 
all .=.- instructions. 



.MAIN, RT»il MACRO VM02-12 PAGE i 



I 


000000* 


.CSECT TEST 
,GL0BL. A,8,C 


3 




.MCALL ,.V2..,.REGDEF 


« 000090 




» » "2 » • 


5 000000 




.REGDEF 


6 000000 


0000006 


.WORD A 


7 000002 


016701 8TARTJ 
000006G 


MOV Af6,Rl 


8 000006 


060127 


ADO R1,(*C)+ 


9 000010 


000000G 


,WORD B 


10 


000002' 


, » , • 1 


11 0001712 


000004G 


.WORD A+4 


12 


000002* 


• ».*2 


13 00002 


000002G 


,W0RD B+2 


14 


000000* 


. t,mH 


15 00000 


000006G 


.WORD C+6 


16 


000002* 


.END START 
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6.4 GLOBAL SYMBOLS 

Global symbols provide the link, or communication, between object 
modules. Global symbols are created with the .GLOBL assembler 
directive (see Chapter 5) . If the global symbol is defined in an 
object module (as a label or by direct assignment) , it is called an 
entry symbol and other object modules can reference it. If the global 
symbol is not defined in the object module, it is an external symbol 
and is assumed to be defined (as an entry symbol) in some other object 
module . 

As the Linker reads the object modules it keeps track of all global 
symbol definitions and references. It then modifies the instructions 
and/or data which reference the global symbols. Undefined globals are 
printed on the console terminal after pass 1 (or pass 2 if a library 
file is also linked) . 



6.5 INPUT AND OUTPUT 

Linker input and output is in the form of modules; one or more input 
modules (object files produced by either assembler or FORTRAN IV) are 
used to produce a single output (load) module. 



6.5.1 Object Modules 

Object files, consisting of one or more object modules, are the input 
to the Linker (the Linker ignores files which are not object modules) . 
Object modules are created by the RT-11 assemblers or FORTRAN IV. The 
Linker reads each object module at least twice (three times if library 
files are linked) . During the first pass each object module is read to 
construct a global symbol table and to assign absolute values to the 
control section names and global symbols. If library files are 
linked, a second pass is needed to resolve the undefined globals from 
the library files and force their associated object modules into the 
root j on the final pass, the Linker reads the object modules, links 
and relocates the modules and outputs the load module. 



6.5.2 Load Module 

The primary output of the Linker is a load module which may be loaded 
and run under RT-11. The load module is output as a save image file 

(SAV) for use under a Single- Job system or the background job. Under 
an F/B System, the /R switch must be used to produce a REL 

(reloctable) format foreground load module if the job is to run in the 
foreground. An absolute load module (LDA) is produced if the module 
is to be loaded by the Absolute Loader. 

The load module for a save image file is arranged as follows: 



Root Segment 



Overlay 

Segments 

(optional) 



For a REL image file, the load modules are arranged as: 
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Root Segment 


Overlay 

Segments 

(optional) 


Resident 

REL 

Blocks 


Overlay 
REL Blocks 
(optional) 



The first 256-word block of the root segment (main program) contains 
the memory usage map and the locations used by the Linker to pass 
program control parameters. The memory usage map outlines the blocks 
of memory used by the load module and is located in locations 360 to 
377. 

The control parameters are located in locations 40-50 and contain the 
following information when the module is loaded: 

Address Information 

40 ; Start Address of program 

42: Initial setting of R6 (stack pointer) 

44: Job Status Word 

46: USR Swap Address (0 implies normal location) 

50: Highest Memory Address in user's program 

For a foreground link the following additional parameters contain 
information: 

34,36: TRAP Vector 

52: Size of Resident (words) 

54: Sum of the Resident and largest Overlay Region 

(words) 
56: F/B Identification 
60: Address of Resident REL Block 

Memory locations 0-476 (comprising the interrupt vectors and system 
communication area) may be assigned initial values by using an .ASECT 
assembler statement and will appear in block of the load module, but 
there are restrictions on the use of .ASECTs in this region. The 
Linker does not permit an .ASECT of location 54 or of locations 
360-377 (the memory usage map is passed in those locations). In 
addition, for foreground links, an .ASECT of words 40-60 is not 
permitted (additional parameters are passed to FRUN in those 
locations ) . 

Any location which is not restricted may be set with an .ASECT, but 
caution should be used in changing the system communication area. 
Restricted areas, such as the region 360-377, must be initialized by 
the program itself. There are no restrictions on .ASECTs if the 
output format is LDA. 

Locations in the region 0-476 which are initialized by an .ASECT in a 
program may never be loaded when the program is executed. There are 
two reasons for this. For background tasks (or the Single-Job system) 
the R, RUN, and GET commands will not load an address protected by the 
monitor's memory protection map. The addresses normally protected 
include such important areas as the system device and console device 
vectors, but protection may be extended dynamically (e.g., by a 
foreground task issuing a .PROTECT call). For foreground tasks, the 
FRUN command will load only locations 34-50 (34 is the TRAP 
instruction vector) and all other .ASECTs are ignored. The procedure 
for loading these locations is to do so at run-time using MOV 
instructions. 
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6.5.3 Load Map 



If requested, a load map is produced following the completion of the 
initial pass(es) of the Linker. This map, shown in Figure 6-1, 
diagrams the layout of memory for the load module. 

Each.CSECT included in the linking process is listed in the load map. 
The entry for a.CSECT includes the name and low address of the section 
and its size (in bytes). The remaining columns contain the entry 
points (or globals) found in the section and their addresses. 

The map begins with the name of the load module and the date of 
creation. The modules located in the root segment of the load module 
are listed next, followed by those modules which were assigned to 
overlays in order by their region number (see Section 6.6). Any 
undefined global symbols are then listed. The map ends with the 
transfer address (start address) and high limit of relocatable code. 

NOTE 

The load map will not reflect the 
absolute addresses for a REL file 
created to be run as a foreground job; 
the base relocation address specified at 
FRUN time must be added to obtain the 
absolute addresses. 

For example, assume the FRUN command is used to run the program 
RELTST: 

,FRUN RELTST/P 
LOADED AT 137:1.50 

When linked, the following load map is produced: 



RTMl LINK X03-16 


LOAD MAP 










RELTST, REL 




0-3-SEP" 


74 










SECTION AQOR 


SIZE 


ENTRY 


AOOR 


ENTRY 


ADDR 


ENTRY 


AODR 


, ASS, 000000 


000350 


STKSIZ 


000012 


SPVEC 


000320 


SCRPOS 


001750 


T9TVTI 000330 


000336 














SGTB 000676 


001116 


SDSINT 


000676 


SSTOPP 


000710 


SNR 


000752 






STACKP 


000764 


STATBF 


001106 


SOPC 


001142 






SLINKP 


001146 


SLCOIS 


001150 


SLCNT 


001152 






S08VEC 


001134 


STACKE 


001202 


SOPILE 


001226 






SYS 


001244 


SBLANK 


001206 


SLINK 


001252 






sbvpas 


001256 


SCTRAK 


001260 


SLSRA 


001276 






SCUSER 


001302 


SNULL 


001316 


SXT 


001326 






SYT 


001330 


SLPINT 


001404 


SLPSUF 


001434 






SNR8UF 


001446 


STRAKC 


001562 


SXSTOR 


001572 






SY8T0R 


001574 


S80INT 


001670 


SV8TIN 


001676 






8VSTP 


001722 


SPDV1 


001756 


SPEXIT 


001764 



6-7 



Linker 

OVERLAY REGION 000001 SEGMENT 000001 

SGT1 002016 000210 SVINIT 00201b SVFDEL 002100 SV8T0P 002114 

SVN8RT 002130 SVRHOV 002174 SV3TRT 002214 

SGT2 002226 000102 SVBLNK 002226 SVRSTR 002256 SV3RCH 002300 

SGT3 002330 000130 SVTRAK 002330 BVLPEN 002410 SVSTPM 002420 

INOSYN 002430 SSYNC 002440 SNAME 002430 

OVERLAY REGION 000001 SEGMENT 000002 

SGT4 002016 000602 SVRTLK 002016 SVUNLK 002300 SYLSET 002404 

SVSCRL 002512 

TRANSFER ADDRESS > 000350 
HIGH LIMIT « 002620 



To determine the address of TSTVT1, 137150 must be added to 000350; 
thus 137520 is the absolute address of TSTVT1. The transfer address 
is 137150 plus 350, or 137520. 



6.5.4 Library Files 

The RT-11 Linker has the capability of automatically searching 
libraries. Libraries are composed of library files — specially 
formatted files produced by the Librarian program (Chapter 7) which 
contain one or more object modules. The object modules provide 
routines and functions to aid the user in meeting specific programming 
needs. (For example, FORTRAN has a special library containing all 
necessary computational functions — TAN, ATAN, etc.) By using the 
Librarian, libraries can be created and updated so that routines which 
are used more than once, or routines which are used by more than one 
program, may be easily accessed. Selected modules from the 
appropriate library file are linked as needed with the user program to 
produce one load module. Libraries are further described in Section 
6.7 and in Chapter 7. 

NOTE 

Library files that have been combined 
under PIP are illegal as input to both 
the Linker and the Librarian. 
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RT-1 1 LINK V03-01 LOAD MAP 
SQRT ,5AV 19-SEP-74 

SECTION ADDR SIZE ENTRY ADDR ENTRY AQOR ENTRY AODR 

, ASS. 0(913019(9 0010130 SUSRSW 000000 SV005A 000001 SNLCHN 000006 

SLRECL 000210 STRACE 004737 

001000 000220 

001220 001364 SUTI 001246 

002604 002300 OCIS 002604 ICIS 002612 SGET 0027T2 

RCI4 003006 OCOS 003712 ICOS 003720 

GCOS 004144 FCOS 004152 ECOS 004156 

DCOS 004164 

005104 000160 ISMS 005104 SISNTR 005110 LSNS 005124 

SLSNTR 005130 

005264 000102 MOISSS 005264 MQLSSS 005264 MQIS3M 005270 

M0IS5A 005274 MOI$IS 005300 MQLSIS 005300 

RELS 005300 MOISIM 005304 MQISIA 005310 

MQISMS 005314 MQISMM 005320 MQISMA 005324 

NOIS0S 005330 MOIS0M 005334 MQIS0A 005340 

MOIS1S 005344 MOISIM 005352 MQIS1A 005360 

005366 000020 IFR$ 00536b IFWS 005400 

005406 000046 EOL» 005406 

005450 000062 TVUS 005454 TVFS 005462 TVOS 005470 

TVQ$ 005476 TVP$ 005504 TVIS 005512 

005536 000036 CAIS 005536 CALS 005544 

005574 000174 SQRT 005574 

005770 000026 MOFSRS 005770 MOFSRM 005776 MOFSRA 006006 

MOFSRP 006012 

006016 000044 NMIS1M 006016 NMISII 006026 BLES 006034 

BEGS 006036 BfcTS 006044 BGES 006046 

BRAS 006050 BNES 006054 BITS 006056 

006062 000072 POOS 006062 EXIT 006074 STPS 006074 

0136154 000002 SAOTS 006154 
SERRTB 006156 000100 
SERRS 006256 002637 

011116 001534 $H0 011600 

012652 000202 SFMTDR 012652 SFMTDW 012702 SINITI 012750 

013054 000416 SCLOSE 013054 

013472 000106 ICIS 013472 LCOS 013540 

013600 000302 SGETRE 013600 8TTYIM 013722 

014102 000262 SPUTRE 014102 

014364 000106 SFCHNU 014364 

01U472 0KJ0674 SOPEN 014472 

015366 000110 SDUMPL 015366 

015476 000414 SPUTBL 015476 SGETBL 015676 SEOFIL 016046 

016112 000042 SWAIT 016112 

TRANSFER ADDRESS ■ 001000 
HIGH LIMIT ■ 016154 



Figure 6-1 
Linker Load Map for Background Job 
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6.6 USING OVERLAYS 



The RT-11 program overlay facility enables the user to have virtually 
unlimited memory space for an assembly language or FORTRAN program. A 
program using the overlay facility can be much larger than would 
normally fit in the available memory space, since portions of the 
program (called overlay segments) reside on a backup storage device 
(disk or DECtape) . 

The RT-11 overlay scheme is a strict multi-region arrangement; it is 
not tree-structured. Figure 6-2 diagrams this scheme. The overlay 
system which the user constructs from his completed program is 
composed of a root segment, memory-resident overlay regions, and the 
overlay segments stored on the backup storage device. The root 
segment is a required part of every overlay program and contains all 
transfer addresses; it must therefore never be overlaid. An overlay 
region corresponds to a run-time area of memory that is shared by two 
or more subroutines (called co-resident subroutines); there is a 
distinct memory area for each overlay region. Overlay segments are 
portions of the save image or REL format file from which the user's 
program is run; these are brought into memory as needed. 



A=A/C 


= Root _ 




B/Oil/C 


= Segment 1 ], 


= Region 1 


C/0 : 1/C 


= Segment 2 •* 




D/0:2/C 


= Segment 3 "N 


= Region 2 


E/0:2 


= Segment 4 J 





Figure 6-2 
Overlay Scheme 



Overlay regions are specified to the Linker via the /0 switch as 
described in Section 6.8.8. The size of the overlay region is 
calculated by the Linker to be the size of the largest group of 
subroutines that can occupy the region at one time. The Linker 
creates the overlay regions and edits the program to produce the 
desired overlays at run- time. 

Figure 6-3 shows a diagram of memory for a program which has an 
overlay structure and Figure 6-4 is a listing of the run-time overlay 
handler. 
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ADDRESS,, 


400 








SYSTEM AREA 




OVERLAY HANDLER 

AND TABLES 
(INCLUDED BY LINKER) 




ROOT SEGMENT 
OF PROGRAM 
(BASICR.FPMP) 




IDENTIFICATION WORD 




OVERLAY 
(BASICX) 


REGION 1 
(BASICE) 




IDENTIFICATION WORD 




OVERLAY REGION 2 
(BASICH) 




• — 

MONITOR 



Figure 6-3 
Memory Diagram Showing BASIC Link With Overlay Regions 



.58TTL. THE RUN. TIME OVERLAY HANDLER 

THfc FOLLOWING CODE IS INCLUDED IN THE USER'S PROGRAM BY THE 
LINKER WHENEVER OVERLAYS ARE REQUESTED BY THE USER. 
59.8 MICROSECONDS (APPRQX) IS AOOEO TO EACH REFERENCE OF 
A RESIDENT OVtRLAY SEGMENT, 

THfc RUN-TIME OVERLAY HANDLER IS CALLED BY A DUMMY 
SU0RUUUNE OP THfc FOLLOWING FQRMI 



JSR R5,iQVKH 
.WORD <OVERLAY ftp 
,WURQ «ENTRY ADDR» 



/CALL TO CUMMON COUt 
l# OF OESIREO SEGMENT 
JACTUAL CORE ADOR 



ONfc OyMMY ROUTINE OF THE ABOVE FORM IS STORED IN THE RESIDENT 
PORTION Of THfc USeR'3 PROGRAM FOR EACH ENTRY POINT TO 
AN OVERLAY SEGMENT, ALL REFERENCES TO THE ENTRY POINT ARE 
MODIFIfcU BY THE LINKER TO INSTEAD BE REFERENCES TO THE APPRO- 
PRIATE DUMMY HOUTINE. EACH OVERLAY SEGMENT IS CALLED INTO 
CORE AS A UNIT AND MUST BE CONTIGUOUS IN CORE, AN OVERLAY 
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I SeSMfcNT MaV HAVt ANY NUMBER OP ENTRY POINTS, TO THE LIMITS 
I OF CORE MEMORY. ONLY ONE SEGMENT AT A TIMS MAY OCCUPY AN 
! OVfcRLAY REGION, 



| RESTRICTIONS! 

f SINCE REFERENCES TO OVERLAY SESMENTS ARE AUTOMATICALLY TRANS- 

| LAIED dY THE LINGER INTO REFERENCES TO DUMMY SUBROUTINES* 

I THfc PROGRAMMER MUST NOT ATTEMPT TO REFERENCE DATA In AN OVER" 

I LAY 0Y USING GLOBAL SYMBOLS, 



SQVRHJ 



SOyRHBI 



SENTfcRl 



SOVTAB'1000+SOVRHe-SQVRH 



MUV 

Muy 

MUV 



MUV 
BR 
MDV 
10VRHAI AOO 
MUV 



LMP 
dfeQI 

•KEAUn 

BCS 

MOV 

MOV 

MOV 

MOV 

RTS 



ReifCSP) 

Rli-(SP) 

R2i-CSP) 



CRS3*iR0 

SFIRST 

RfeiiRl 

*$QVTAb.6,Rl 
(Rn*#R2 
R0i#R2 
SENTER 



>PIC* UP OVERLAY NUMBER 
/FIRST CALL ONLY * * * 



fCALC TABLE ADDR 

JGET CORK' ADDR OF OVERLAY REGION 

>IS OVERLAY ALREADY RESIDENT? 

>YES» BRANCH TO IT 
17#R2, IRIJ*, (R1J* ;REAO FROM OVERLAY FILE 
»ERR 

CSP)*»R2 fRESTQRE USER'S REGS 
CSP)+,R1 
C5P)*#R0 

#R!>,R9 |G|T ENTRY ADDRESS 

R& lENTtP OVERLAY ROUTINE AND 

IRESTORfc. USER'S R5 



SFIRSTS MUV 
MOV 

SHROOTD .WORD 
MOV 

SHOVLYI .WORD 



»U5k)0,$UVRHB IRESTORt SWITCH INSTR 



iSI 

SgffRi 
SOVRHEl 



CLR 

CMP 

«LO 

BR 

EMT 

.BYTE 



CPCJ*,R1 



CPC)*,R2 

* 

CRD* 

RJ# R2 

IS 

SOVHHB 

370 

a, 373 



ISTART ADDR FOR CLEAR OPERATION 

/HIGH ADDR Of ROOT SEGMENT 

JCOUNT 

»MIGM LIMIT OF OVERLAYS 

>CLEAR ALL OVERLAY REGIONS 



fAND RETURN TO CALL IN PROGRESS 
IGENtRATE ALWAYS FATAL ERROR 
JANO DISREGARD SOFT ERROR 



f OVERLAY SESMgNT TABLE POLLOwSl 

I SOVTABl ,wORO «CO*E ADDR>, «RELATI VE BLK»><WQRD COUNT> 

i Three wurds per entry, one entry per overlay segment. 

I ALSO* THERE 13 0N£ wORD PREFIXED TO EACH OVERLAY REGION 

i that identifies the segment currently resident in that region. 

I THIS WORD IS AN iNDfcX INTO THE SOVTaB TABLE. 



Figure 6-4 
The Run-Time Overlay Handler 
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There is no special code or function call needed to use overlays but 
the following rules must be observed when referencing parts of the 
user program which might be overlaid. 

1. Calls or branches to overlay segments must be made directly 
to entry points in the segment. Entry points are locations 
tagged with a global symbol (refer to Chapter 5, Section 
5.5.10). For example, if ENTER is a global tag in an overlay 
segment : 

JMP ENTER is legal, but 

JMP. ENTER+6 is illegal. 

2. Entries in overlay segments can be used only for transfer of 
control and not for referencing data within an overlay 
section (e.g., MOV ENTER, R4 is illegal if ENTER is in an 
overlay segment, but MOV #ENTER,R7 is legal because it is 
used for transfer of control) . A violation of this rule 
cannot be detected by the assembler or Linker so no error is 
issued; however, it can cause the program to use incorrect 
data. 

3. When calls are made to overlays, the entire return path must 
be in memory. This will happen if these rules are followed: 

Calls (with expected return) may be made from an overlay 
segment only to entries in the same segment, the root 
segment, or an overlay segment with a greater region 
number. 

Calls to entries in the same region as the call must be 
entirely within the same segment, not another segment in 
the same region. 

Jumps (with no expected return) can be made from an 
overlay segment to any entry in the program. However, 
jumps should not reference an overlay region whose number 
is lower than the region from which the last unreturned 
call was made (e.g., if a call was made from region 3, 
then no jumps should reference regions 1, 2 or 3 until 
the call has returned) . 

Subroutines in the root segment may be called from 
overlay segments; in turn, they may call entries from 
the same overlay segment which called them, or from the 
root segment, or from another overlay segment with a 
greater region number. Such subroutines are considered 
part of the overlay segment which called them. 

4. A .CSECT name cannot be used to pass control to an overlay. 
It will not cause the appropriate segment to be loaded into 
memory (e.g., JSR PC,OVSEC is illegal if OVSEC is used as a 
.CSECT name in an overlay). As stated in 1 above, a global 
symbol must be used to pass control from one segment to the 
next. 

5. Channel 17 (octal) cannot be used by the user program because 
overlays are read on that channel. 

6. Object modules acquired from a library file cannot be placed 
into overlays. 
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7. Library files may not be specified on the same command line 
as an overlay. 

8. Overlay regions must be specified in ascending order and are 
read-only. Unlike USR swapping, an overlay segment does not 
save the segment it is overlaying. Any tables, variables, or 
instructions that are modified within a given overlay segment 
are re-initialized to their original values in the SAV or REL 
file if that segment has been overlaid by another segment,, 
Any variables or tables whose values must be maintained 
across overlays should be placed in the root segment. 

9. .ASECTs of any size in an overlay foreground link are 
illegal; the error message ?ILL ASECT? is printed and the 
line is aborted. 

The following information should be noted when writing FORTRAN 
overlays . 

1. When dividing a FORTRAN program into a root segment and 
overlay regions (and subsequently dividing each overlay 
region into overlay segments) , routine placement should be 
carefully considered. The user should always remember that 
it is illegal to call a routine located in a different 
overlay segment in the same overlay region, or an overlay 
region with a lower numeric value (as specified by the Linker 
overlay switch, /0:n) from the calling routine. The user 
should divide each overlay region into overlay segments which 
never need to be resident simultaneously (i.e., if segments A 
and B are assigned to region X, they cannot call each other 
because they occupy the same locations in memory) . 

2. The FORTRAN main program unit must be placed in the root 
segment . 

3. In an overlay environment, subroutine calls and function 
subprogram references may refer only to one of the following: 

A FORTRAN library routine (e.g., ASSIGN, DCOS) 

A FORTRAN or assembly language routine contained in the 
root segment 

A FORTRAN or assembly language routine contained in the 
same overlay segment as the calling routine 

A FORTRAN or assembly language routine contained in a 
segment whose region number is greater than that of the 
calling routine 

4. In an overlay environment, COMMON blocks must be placed so 
that they are resident when referenced. Blank COMMON is 
always resident since it is always placed in the root 
segment. All named COMMON must be placed either in the root 
segment, or into the segment whose region number is lowest of 
all segments which reference the COMMON block. A named 
COMMON block cannot be referenced by two segments in the same 
region unless the COMMON block appears in a segment of a 
lower region number. The Linker automatically places a 
COMMON block into the root segment if it is referenced by the 
FORTRAN main program or by a subprogram that is located in 
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the root segment. Otherwise the Linker places a COMMON block 
in the first segment encountered in the Linker command string 
that references that COMMON block. 

5. All COMMON blocks which are initialized (by use of DATA 
statements) must be so initialized in the segment in which 
they are placed. 

Refer to the RT-ll/RSTS-11 FORTRAN IV User's Guide for more details. 

The .ASECT never takes part in overlaying in any way (i.e., if part of 
an .ASECT is destroyed by overlay operations, it is not restored by 
the overlay handler) . 

The aforementioned sets of rules apply only to communications among 
the various modules that make up a program. Internally, each module 
must only observe standard programming rules for the PDP-11 (as 
described in the PDP-11 Processor Handbook and in Chapter 5) . 

It should be noted that the condition codes set by a user program are 
not preserved across overlay segment boundaries. 

The Linker provides overlay services by including a small resident 
overlay handler (Figure 6-4) in the same file with the user program to 
be used at program run- time. This overlay handler plus some tables 
are inserted into the user's program beginning at the bottom address 
computed by the Linker. The Linker moves the user's program up in 
memory by an appropriate amount to make room for the overlay handler 
and tables, if necessary. 



6.7 USING LIBRARIES 

Libraries are specified in a command string in the same fashion as 
normal modules; they may be included anywhere in the command string, 
with the exception of overlay lines. If a global symbol is undefined 
at the time the library is encountered in the input stream and a 
module is included in the library which includes that global 
definition, that module is pulled from the library and linked into the 
load image. Only the modules needed to resolve references are pulled 
from the library; unused modules are not linked. 

NOTE 

Modules in one library may call modules 
from another library; however, the 
libraries must appear in the command 
string in the order in which they are 
called. For example, assume module X in 
library ALIB calls SQRT from the FORTRAN 
library. To correctly resolve all 
globals, the order of ALIB and the 
FORTRAN library should appear in the 
command line as: 

*z^b?al:i:b/f 
or *z^Bs>ai...:i:b>-i ;; 'orl:i:b 
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Module B is the root. It calls X from 

ALIB and brings X into the root. X in 

turn calls SQRT which is brought from 
FORLIB into the root. 

FORTRAN libraries cannot precede their root segment in a command line 
as this creates a bad transfer address. For example: 

*X=-ROOT/F 
flX-ROOT,- FORLIB 

are legal, but: 

* X -FOR LIB* ROOT 

is not. Unpredictable results will occur. 



6.7.1 User Library Searches 

Object modules from the named user libraries built by the Librarian 
are relocated selectively and linked by the Linker. The RT-11 Linker 
searches a specified library file during the library pass as follows 
(refer to Figure 6-5 for a flowchart representation of this process) : 

1. If there are any undefined globals in the Linker's tablet 
when a library is encountered in the command string, proceed 
to step 2; otherwise skip this library (go to step 5) . 

2. Read the library directory. 

3. If any of the undefined globals can be defined by a module 
in this library, include the relevant module into the linked 
output file; otherwise, go to step 5. 

4. If any undefined globals remain in the Linker's table and 
they have not been looked for in the library, return to step 
2; otherwise go to step 5. 

5. Close the library file. 

6. Go to the next element in the command string. 

This search method allows modules to appear in any order in the 
library. Any number of libraries may be specified in a link, and they 
may be positioned anywhere, with the exception of overlay segments and 
the restrictions noted in Section 6.7. 
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c 



EXIT PASS 




NO 



» PROCESS FILE 



READ 
LIBRARY DIRECTORY 



SEARCH 

UNDEFINED GLOBALS 

FROM LIBRARY 




YES 



YES 




CLOSE LIBRARY 



Figure 6-5 
Library Searches 



NOTE 



For faster Linker performance, the user 
should specify all object files before 
library files, and all user library 
files before the system library files. 
For example: 
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*A^As>ByUSEI...:i:B/F 

where A and B are object modules, USELIB 
is a user-created library file, and /F 
denotes the default FORTRAN library, 
FORLIB. 

Libraries are input to the Linker as any other input file. Assume the 
following command string to the Linker: 

* TASK 0:1. . SAV » LP t ^MAIN , OBJ , MEASUR , OBJ 

This causes program MAIN. OBJ to be read from DK: as the first input 
file. Any undefined symbols generated by program MAIN. OBJ should be 
satisfied by the library file MEASUR. OBJ specified in the second input 
file. The load module, TASK01.SAV is put on DK: and a load map goes 
to the line printer. 



6.8 SWITCH DESCRIPTION 

The switches summarized in Table 6-1 are described in detail below. 

6.8.1 Alphabetize Switch 

The /A switch requests the Linker to list linked modules in 
alphabetical order as follows: .CSECTs, module names, and entry 
points within modules. The load map is normally arranged in order by 
module address as shown in Figure 6-1. Figure 6-6 is an example of an 
alphabetized load map for a background job. 



6.8.2 Bottom Address Switch 

The /B switch specifies the lowest address to be used by the 
relocatable code in the load module. When /B is not specified, the 
Linker positions the load module so that the lowest address is 
location 1000 (octal) , or for a foreground link. If the .ASECT 
length is greater than 1000, the length of .ASECT is used. 

The form of the bottom switch is: 

/B:n 

n is a six-digit unsigned octal number which defines the bottom 
address of the program being linked. An error message results if n is 
not specified as part of the /B command. 

If more than one /B switch is specified during the creation of a load 
module, the first /B switch specification is used. 

NOTE 

The bottom value must be an unsigned 
even octal number. If the value is odd, 
an error message is generated. 
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RT-ll LINK V03-01 LOAD MAP 

SORT ,SAV 1SUSEP-74 

SECTION ADOR SIZE ENTRY AODR ENTRY AODR ENTRY ADDR 

, ASS, 00069(30 001000 SLRCCL 9130210 SNLCHN 000006 SUSRSlrf 000000 

STRACE 000737 SV005A 000001 

001000 00022(0 

001220 001364 SOTI 001216 

002600 002300 OCOi 004164 ECOS 00415b FCOS 004152 

GCOS 004144 XCIS 002612 ICO$ 003720 

OCI$ 002604 OCOS 003712 RCIS 003006 

SGET 002772 

005104 000160 ISNS 005100 LSN$ 005124 SISNTR 005110 

SLSNTH 005130 

005264 000102 MOISIA 005310 MQISIM 005304 MQISIS 005300 

MOISMA 005324 MOISMM 005320 M0I$M3 005314 

MOISSA 005274 MOISSM 005270 MQISSS 005264 

MOIS0A 005340 MOIS0M 005330 MOIS0S 005330 

MOISIA 005360 MOISIM 005352 M0I$18 005344 

MQUSIS 005300 MOLSSS 005260 RELS 005300 

095366 000020 1FR$ 005366 XFW$ 005400 

005406 000046 fcOLS 005006 

005454 000062 TvD$ 005470 TVF$ 005462 TVIS 005512 

TVLS 005454 TVPS 005504 TVOS 00547b 

005536 000036 CAIS 005536 CALS 005544 

005570 000174 SBRT 005570 

005770 000026 MOKSRA 006006 MOF$RM 005776 MOFSRP 006012 

MOFSRS 005770 

006016 000040 BEGS 006036 BGE$ 00600b BGT$ 006044 

BUES 006034 fiLTS 006056 SNES 006054 

bRAS 006050 NMIS1I 006026 NMIS1M 006016 

tiQbdhi 000072 EXIT 00b074 POOS 006062 STPS 00607a 

006150 000002 SAOTS 006154 
StRRTS 006156 000100 
SERR5 006256 002637 

01111b 001534 $FIO 011600 

012652 000202 SFMTOR 012652 SFMTDW 012702 SINITI 012750 

0l3fci54 000416 SCLOSE 013054 

01347c! 000106 LCIS 013472 LCO$ 013540 

013600 000302 SGETRE 013600 $TTYIN 013722 

014102 000262 SPUTRE 014102 

014360 000106 SfCHNL 014364 

014472 000674 SOPEN 014472 

015366 000110 SOUMPL 015366 

01547b 000414 StOFIL 01604b SGETBL 015676 SPUTBL 015476 

016112 000042 SWAIT 016112 

TRANSFER ADDRESS ■ 001000 
HIGH LIMIT * 016150 

Figure 6-6 

Alphabetized Load Map for a Background Job 
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/B is illegal with foreground links, 
Example : 

* U T P U T > I... P % ~ I. N P U T / B I 5 
6.8.3 Continue Switch 



(0 is assumed.) 



Causes the input file to be 
linked starting at location 
500 (octal) . 



The Continue switch (/C) is used to allow additional lines of command 
string input. The /C switch is typed at the end of the current line 
and may be repeated on subsequent command lines as often as necessary 
to specify all input modules for which memory is available. If memory 
is exceeded, an error message is output. A /C switch is not entered 
on the last line of input. 



Example: 



# OUTPUT j I 



:i:nput/c; 



Input is to be continued on 
the next line; the Linke3: 
prints an asterisk. 



6.8.4 Default FORTRAN Library Switch 

By indicating the /F switch in the command line, the FORTRAN library,. 
FORLIB.OBJ on the default device (SY:), is linked with the other 
object modules specified; the user does not need to specify FORLIB., 
For example: 

*F : 'ILE yl...PS^AB,OBJ/F 

The object module AB.OBJ and the FORTRAN library FORLIB are linked 
together to form a load module called FILE.SAV. (Note that the FORLIB 
default is SY: FORLIB. OB J, not DK: FORLIB. OB J.) 



6,8.5 Include Switch 

The /I switch allows subsequent entry at the keyboard of global 
symbols to be taken from any library and included in the linking 
process. When the /I switch is specified, the Linker prints: 

LIBRARY SEARCH: 

Reply with the list of global symbols to be included in the load 
module; type a carriage return to enter each symbol in the list. A 
carriage return alone terminates the list of symbols. This provides a 
method for forcing modules (which are not called by other modules) tc 
be loaded from the library. 



Example : 



*outputvLpj=:i:nput!-: 
library search: 

A <CR> 

GETSYM <CR> 
CHAR <CR> 
CHFLG <CR> 
<CR> 



.IB/ 



Linker prints LIBRARY SEARCH: 

User enters A, GETSYM, etc. which are 
to be included in the linking process. 
Each symbol is entered by typing 
a carriage return; the list is termi- 
nated by an additional carriage return. 
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6.8.6 LDA Format Switch 

The LDA format switch (/L) causes the output file to be in LDA format 
instead of save image format. The LDA format file can be output to any 
device, including devices that are not block-replaceable such as paper 
tape or cassette, and is useful for files which are to be loaded with 
the Absolute Loader. The default extension .LDA is assigned when the 
/L switch is used. 

The /L switch cannot be used in conjunction with the overlay switch 
(/O) or in foreground links (/R) . 



Example: 



* D KHU.IT ? 



:i:ns :ln2/i... 



Links disk files IN and IN2; 
outputs an LDA format file 
OUT. LDA to the system device 
and a load map to the line 
printer. 



6.8.7 Modify Stack Address 

The stack address, location 42, is the address which contains the 
user's stack pointer. The /M switch allows terminal keyboard 
specification of the user's stack address. 

The form of the switch is: 

/M:n 

n is an even unsigned 6-digit octal number which defines the stack 
address. If n is not specified, the Linker prints the message: 

STACK ADDRESS = 

In this case, specify the global symbol whose value is the stack 
address. A number cannot be specified, and if a nonexistent symbol is 
specified, an error message is printed and the stack address is set to 
the system default (1000 for save files, for REL) . 

Direct assignment (via .ASECT) of the stack address within the program 
takes precedence over assignment with the /M switch. 



Example ; 



* OUTPUT™ I NPUT/M 



STACK ADDRESS 



BE 



6.8.8 Overlay Switch 

The Overlay switch (/O) is used to segment the load module so that the 
entire program is not memory resident at one time (overlay feature) . 
This allows programs larger than the available memory to be executed. 
The switch has the form: 

/0:n 
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where n is an unsigned 
specifying the overlay 
switch must follow (on 
modules to which it 
specified on a command 
the first command line 
continuation switch must be used. 



octal number (up to six digits in length) 
region to which the module is assigned. The /0 
the same line) the specification of the object 
applies, and only one overlay region can be 
line. Overlay regions cannot be specified on 
as this is the root segment. Therefore, the /C 



Co-resident overlay routines (a group of subroutines which occupy the 
overlay region and segment at the same time) are specified as follows: 

* OB J A , OB JB , OB JC/O : n/C 
*0B JD , OB JE/O : m/C 



All modules mentioned until the next /0 switch will be co-resident 
overlay routines. If at a later time the /0 switch is given with the 
same value previously used (same overlay region) , then the 
corresponding overlay area is opened for a new group of subroutines. 
The new group of subroutines will occupy the same locations in memory 
as the first group, but not at the same time. For example, if 
subroutines in object modules R and S are to be in memory together, 
but are never needed at the same time as T, then the following 
commands to the Linker make R and S occupy the same memory as T (but 
at different times) : 

*ma:i:nh...p^root/c 
*r»s/du/c 

*T/0!1 
The above could also be written as: 

*ma:i:Ns.i...p^root/(:; 

*R/OH/C 

*s/c 

*T/OU 



Example : 



* output , i...p ;^:i:nput/c 

jKOBJA/OU/C 
JK0BJB/CK2 



Establishes two overlay 
regions 



Overlays must be specified in order of increasing region number, 
example: 



For 



. r l:i:nk 

*B/(.m/c 
*c:/(k:i./c 
#1:1/0 u/c 
#ErF"/c)t2/<:; 



The following overlay specification is illegal since the overlay 
regions are given in a random numerical order (an error message is 
printed in each case) : 
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»R LINK 

*b/o;:i./c 
/o ignored 

*C/0}:l./C 

/o ignored 

*g/d:;?/c 

*H/0!3/C 
*E^F/0J2 
/a IGNORED 



6.8.9 REL Format Switch 



The REL format switch (/R) causes the output file to be in REL format 
for use as a foreground job under the F/B Monitor. REL format files 
must be used in a foreground job (they may not be used under a 
Single- Job system). The /R switch assigns the default extension .REL 
to the output file. 

Example : 

*DT2.}F : 'ILL : ;:o»LF :, !~F:CLE:[»NEXT/R Disk files FILEI and NEXT are 

linked and output to DT2 as 
FILEO.REL; a load map is 
output to the line printer. 

The /B and /L switches cannot be used with /R since a foreground REL 
job has no bottom address and is always relocated by FRUN. A ?BAD 
SWITCH? error message is generated if this is attempted. 



6.8.10 Symbol Table Switch 

Use of the symbol table switch in the command line instructs the 
Linker to allow the largest possible memory area for its symbol table 
at the expense of making the link process slower. With the /S switch, 
library directories are not made resident in memory, but are left on 
disk. For example: 

* U T F ■> I... P t ==■■ I N P U T * B J » I... I B R 1 . B J , I... I B R 2 * B J / S 

The directories of the library files LIBR1 and LIBR2 are not brought 
into memory, resulting in more room in the symbol table but longer 
link time. 

If the /S switch is not used and the memory available to the Linker is . 
approximately 10K or larger, the library directory is brought into I 
memory (providing there is room) ; the directory is kept there until 
the library has been completely processed, thus reducing the size of 
the Linker's symbol table. If there is not enough room in memory for 
the directory (as is the case in an 8K system) , the Linker determines 
this and leaves the directory on disk regardless of whether the /S 
switch was- used or not. 

The /S switch should be used only if an attempt to link a program 
failed because of symbol table overflow. Often, use of /S will allow 
the program to link. 
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6.8.11 Transfer Address Switch 

The transfer address is the address at which a program is to be 
started when executed via an R, RUN, or FRUN command. The Transfer 
Address switch (/T) allows terminal keyboard specification of the 
start address of the load module to be executed. This switch has the 
form: 

/T:n 

where n is a six-digit unsigned octal number which defines the 
transfer address. If n is not specified, the message: 

TRANSFER ADDRESS - 

is printed. In this case, specify the global symbol whose value is 
the transfer address of the load module, followed by a carriage 
return. A number cannot be specified in answer to this message. When 
a nonexistent symbol is specified, an error message is printed and the 
transfer address is set to 1 (so that the program cannot be executed) . 

If the transfer address specified is odd, the program does not start 
after loading and control returns to the monitor. 

Direct assignment (.ASECT) of the transfer address within the program 

takes precedence over assignment with the /T switch. The transfer 

address assigned with a /T has precedence over that assigned with a 
.END assembly directive. 



Example: 



lHPROO^PROGJ. yPR0G2y0DT/T The files PROG1.0BJ,PROG2.0BJ 
TRANSFER ADDRESS =-■ and ODT.OBJ are linked to- 

O.ODT gether and started at ODT's 

transfer address. 



6.9 LINKER ERROR HANDLING AND MESSAGES 

The following error messages can be output by the Linker. The 
messages enclosed in question marks are output to the terminal) the 
other messages are only warnings and are included in the load map. If 
a load map is not requested in the command string, all messages are 
output to the terminal. 

Message Meaning 

additive REF OF xxxxxx Rule 1 of overlay rules explained in Section 
| AT segment # yyyyyy 6.6 has been violated, xxxxxx represents the 

entry point; yyyyyy represents the segment 
number. 

I ?/B NO VALUE? The /B switch requires an unsigned even 

octal number as an argument. 

?/B ODD VALUE? The argument to the /B switch was not an 

unsigned even octal number. 

?BAD GSD? There is an error in the global symbol 

directory (GSD) . The file is probably not a 
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legal object module. This error 
occurs on pass 1 of the Linker. 



message 



BAD OVERLAY AT SEG # YYYYYY 

Overlay tries to store text outside its 
region; check for a .ASECT in overlay, 
yyyyyy represents the segment number. 



?BAD RLD? 



?BAD SWITCH? 



?BAD X SWITCH IGNORED? 



There is an invalid relocation directory 
(RLD) command in the input file; the file is 
probably not a legal object module. The 
message occurs on pass 2 of the Linker. 

LINK did not recognize a switch specified on 
the first command line. On a subsequent 
command line, a bad switch causes this 
warning message but does not restart the 
Linker. 

LINK did not recognize a switch (x) specified 
in the command line. The switch is ignored 
and linking continues. 



BYTE RELOCATION ERROR AT xxxxxx 

Linker attempted to relocate and link byte 
quantities but failed, xxxxxx represents the 
address at which the error occurred. Failure 
is defined as the high byte of the relocated 
value (or the linked value) not being all 
zero. In such a case, the value is truncated 
to 8 bits and the Linker continues processing 
(for save image and LDA files only; byte 
relocation is completely illegal for REL 
files) . 



?CORE? 
7ERR0R ERROR? 

?ERROR IN FETCH? 
7FILE NOT FND? 
7FORLIB NOT FND? 



?HARD I/O ERROR? 



?ILL ASECT? 



There is not enough memory to accommodate the 
command or the resultant load module. 

An error occurred while the Linker was in the 
process of recovering from a previous system 
or user error. 

The device is not available. 

Input file was not found. 

The user indicated via the /F switch that the 
FORTRAN library, FORLIB, was to be linked 
with the other object modules in the command 
line, and the Linker could not find 
FORLIB. OBJ on the system device. 



A hardware error occurred; 
again . 



try the operation 



The user has attempted to place an .ASECT 
above 1000 in a foreground link or to place 
an .ASECT into an overlay foreground link. 
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?LDA PILE ERROR? 



?/M ODD VAL? 



?MAP FILE ERROR? 



There was a hardware problem with the device 
specified for LDA output or the device was 
full. 

An odd value has been specified for the stack 
address. Control returns to the Linker and 
another command line may be indicated. 

There was a hardware problem with the device 
specified for map output or the device is 
full. 



MULT DEF OF xxxxxx 

?N0 INPUT? 
/0 IGNORED 

?OUTPUT FULL? 
?REL FILE ERR? 

?SAV FILE ERR? 



The symbol, xxxxxx, was defined more than 
once. 

No input files were specified. 

Overlays have been specified in the wrong 
order (see overlay restrictions) ; the overlay 
switch is ignored. 

The output device was full. 

The Linker encountered a problem writing the 
REL file; try the operation again. 

The Linker encountered a problem writing the 
save image file; try the operation again. 



7STACK ADDRESS UNDEFINED OR IN OVERLAY? 

The stack address specified by the /M switch 
was either undefined or in an overlay. The 
stack address is set to the system default. 

7SYMB0L TABLE OVERFLOW? There were too many global symbols used in 

the program. Retry the link using the /S 
switch. If the error still occurs, the link 
cannot take place in the available memory. 

?T00 MANY OUTPUT FILES? The Linker allows specification of only two 

output files. 

TRANSFER ADDRESS UNDEFINED OR IN OVERLAY? 

The transfer address was not defined or was 
in an overlay. 



UNDEF GLBLS 



UNDEFINED GLOBALS 

xxxxxx 

xxxxxx 



A load map was requested and undefined 
globals existed. 

The globals listed (xxxxxx) were undefined. 
If a load map is requested, this condition 
also causes the warning message, UNDEF GLBLS, 
to be printed on the terminal. 
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CHAPTER 7 
LIBRARIAN 



The RT-11 system provides the user with the capability of maintaining 
libraries which may be composed of functions and routines of his 
choice. Each library is a file containing a library header, library 
directory (or entry point table) , and one or more object modules. The 
object modules in a library file may be routines which are repeatedly 
used in a program, routines which are used by more than one program, 
or routines which are related and simply gathered together for ease in 
usage — the contents of the library file are determined by the user's 
needs. An example of a typical library file is the FORTRAN library, 
FORLIB.OBJ. This library is provided with the FORTRAN package and 
contains all the mathematical functions needed for normal usage. 

Object modules in a library file are accessed from another program via 
calls to their entry points; the object modules are linked with the 
program which uses them by the Linker (Chapter 6) to produce a single 
load module. 

The RT-11 Librarian (LIBR) allows the user to create, update, modify, 
list, and maintain library files. 



7.1 CALLING AND USING LIBR 

The RT-11 Librarian is called from the system device by entering the 
command : 

R LIBR 

in response to the dot printed by the Keyboard Monitor. The Command 
String Interpreter prints an asterisk at the left margin on the 
console terminal when it is ready to accept a command line. 

Type CTRL C to halt the Librarian at any time and return control to 
the monitor. To restart the Librarian, type R LIBR or the REENTER 
command in response to the monitor's dot. 
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7.2 USER SWITCH COMMANDS AND FUNCTIONS 



The user maintains library files through the use of switch commands. 
Functions which can be performed include object module deletion, 
insertion and replacement, library file creation, and listing of a 
library file's contents. 



7.2.1 Command Syntax 

LIBR accepts command strings in the following general format: 

*dev:lib,dev:list=dev:input/sl/s2/s3 

where : 

dev: represents a legal RT-11 device specification 

lib represents the library file to be created or 

updated 

list represents a listing file for the library's 
contents 

input represents the filenames of the input object 
modules 

/si,... represents one or more of the switches listed 
in Table 7-1 

Devices and filenames are specified by the user in the standard RT-11 
command string syntax, with default extensions assigned as follows: 

File Extension 

list file: .LLD 

library file: .OBJ 

input files: .OBJ 

If no device is specified, the default device (DK:) is assumed. 

Each input file is made up of one or more object modules, and is 
stored on a given device under a specific filename and extension. 
Once an object module has been inserted into a library file, the 
module is no longer referenced by the name of the file of which it was 
a part, but by its individual module name. (This module name has been 
assigned by the assembler either via a .TITLE statement in the 
assembly source program, or, if no .TITLE statement is present, with, 
the default name .MAIN.; see Chapter 5.) Thus, for example, the input; 
file FORT. OBJ may exist on DT2: and may contain an object module 
called ABC. Once the module is inserted into a library file, 
reference is made only to ABC (not FORT. OBJ) . 



7.2.2 LIBR Switch Commands 

Table 7-1 summarizes the switches available for use under RT-11 LIBR. 
Switches are explained in detail following the table. 
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Table 7-1 
LIBR Switches 



Switch 


Position In 
Command String 


Meaning 


/c 


Any line 
but last 


Command continuation; the command is 
too long for the current line and is 
continued on the next line 


/D 


1st line only 


Delete; delete modules from a library 
file 


/G 


1st line only 


Global deletion; delete entry points 
from the library directory 


/R 


1st line only 


Replace; replace modules in a library 
file 


/u 


1st line only 


Update; insert and replace modules in a 
library file 



There is no switch to indicate module insertion. The function of 
inserting a module into a library file is assumed in the absence of 
other switches. 



7.2.2.1 Command Continuation Switch - The Command Continuation switch 
is necessary whenever there is not enough room to enter a command 
string on one line and additional lines are needed. The /C switch is 
typed at the end of the current line and may be repeated at the end of 
subsequent command lines as often as necessary as long as memory is 
available; if memory is exceeded, an error message is output. A /C 
switch is not entered on the last line of input. 

Command Format: 

*dev:lib,dev:list-dev:inputl,dev:input2,.. . ,/C 
*dev : inputn 



where : 



dev: 
lib 

list 

input 

/C 



represents a device specification 

represents the filename of the 
created or updated 



library 



to 



be 



represents the filename of a listing file containing 
the library file's contents 

represents the filenames of the input modules to be 
inserted into the library 

represents the Continuation switch, indicating 
that the command is to be continued on the following 
line 
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* a i... i b > i... :i: b i... s t ■■■■'■■ d t :i. i m a :i: n , r e s t y f x n / c 
*i:it:l: track 

In this example, a library file is created on the default device (DK:) 
under the filename ALIB.OBJ; a listing of the library file's contents 
is created as LIBLST.LLD also on the default device; the filenames of 
the input modules are MAIN. OBJ, TEST.OBJ, FXN.OBJ, and TRACK. OBJ, all 
from DTI. 

*bl:i:jr:'::ma:i:n/c 
*rk.'i. 5test/c 
*rko:fxn/c 

*i:iTl! TRACK 

A library file is created on the default device, (DK:) under the name 
BLIB. No listing is produced. Input files are MAIN from the default 
device, TEST from RK1:, FXN from RKO : and TRACK from DTI. 

Another way of writing this command line is : 

*bi...:i: b^ma :i: n » rkj. j test , rko j fxn/c 
*dti : TRACK 



7.2.2.2 Creating a Library File - A library file is created whenever 
a filename is indicated on the output side of a command line which 
does not represent a list file. 

Command Format: 

*dev : lib=dev : input 1 ,... ,dev : inputn 
where : 

dev: represents a device specification 

lib represents the filename of the library to be created 

input represents the filenames of the input modules to be 
inserted into the new library 

Example : 

* N E U I... :i: B - F I R S T , 8 E C N B 

A new library called NEWLIB.OBJ is created on the default device 
(DK:). The modules which will make up this library file are in the 
files FIRST. OBJ and SECOND. OB J, both on the default device. 

Assume this command line is next entered: 

* N E W I... I B , I... I S T == T H I R D y F U R T H 

The already existing library file NEWLIB is destroyed when the new 
library file is created. A listing of the library file's contents is 
created under the filename LIST, and the object modules in the files 
THIRD and FOURTH are inserted into the library file NEWLIB. 
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7.2.2.3 Inserting Modules Into a Library - The Insert function is 
aissumed whenever an input file does not have an associated switch; 
the modules in the file are inserted into the library file named on 
the output side of the command string. Any number of input files are 
allowed. If an attempt is made to insert a file which contains an 
entry point or .CSECT having the same name as an entry point or .CSECT 
already existing in the library file, a warning message is printed. 
However, the library file is updated, ignoring the entry point or 
.CSECT in error, and control returns to the CSI; the user may enter 
another command string. 

Although the user may insert object modules which exist under the same 
name (as assigned by the .TITLE statement) this practice is not 
recommended because of the difficulty involved when replacing or 
updating these modules ( refer to Sect ions 7.2.2.4 and 7.2.2.7). 

NOTE 

The library operations of module 
insertion, replacement, deletion, merge, 
and update are actually performed in 
conjunction with the library file 
creation operation. Therefore, the 
library file to which the operation is 
directed must be indicated on both the 
input and output sides of the command 
line; since effectively a "new" output 
library file is created each time the 
operation is performed. The library 
file must be specified first in the 
input field. 

Command Format: 

*dev s lib=dev : lib , dev : inputl , . . . , dev : inputn 

where : 

dev: represents a device specification 

lib represents the filename of an existing library 

file 

input represents the filenames of the modules to be 

inserted into the library file 

Examples 

*i:ixy~dxy ? irri* fa » fb ? fc 

The modules included in the files FA. OBJ, FB.OBJ, and FC.OBJ on DTI: 
are inserted into a library file named DXY.OBJ on the default device. 
The library header and Entry Point Table of the library file are 
updated accordingly (see Section 7.4). 



7,2.2.4 Replace Switch -The Replace function is used to replace 
modules in a library file. All modules contained in the file(s) 
indicated as input will replace existing modules of the same names in 
the library file specified as output. 
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An error message is printed and no modules are replaced if an old 
module does not exist under the same name as an input module, or if 
the user specifies the /R switch on a library file. /R must follow 
each input filename containing modules for replacement. 

Command Format: 

*dev: lib=dev : lib , inputl/R, ... ,dev : inputn/R 

where : 

dev: represents a device specification 

lib represents the filename of an existing library 

file 

input represents the names of the files containing 

modules to be replaced 

/R represents the Replace switch 

Examples : 

* t f :i: i.. .■■■■■■■■ t f :i: i... , i n a > :i: n b / r > :i: n c 

This command line indicates that the modules in the file INB.OBJ are 
to replace existing modules of the same names in the library file 
TPIL.OBJ. The object modules in the files INA.OBJ and INC. OBJ are to 
be added. All files are stored on the default device DK:,. 

* X F 1 1... == T F" 1 1... •> I N A y I N B / R > I N C 

The same operation occurs here as in the preceding example, except 
that this updated library file is assigned the new name XFIL. 



7.2.2.5 Delete Switch - The Delete switch deletes modules and all 
their associated entry points from the library. 

Command Format: 

*dev : lib=dev : lib/D 

where: 

dev * represents the device on which the library file 

exists 

lib represents the filename of an existing library 

file 

/D represents the Delete switch; may be 

positioned anywhere on the input side of the 
command line 

When the /D switch is used, the Librarian prints: 

MOD NAME: 
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The user should respond with the name of the module to be deleted 
followed by a carriage return; he may continue until all modules to 
be deleted have been entered. Typing only a carriage return (either 
on a line by itself or immediately after the MOD NAME: message) 
terminates input and initiates execution of the command line. 



Examples : 



*i:u3 : trap=dt;3 :trafvb 



mob name: 

SGN <CR> 
TAN <CR> 
<CR> 

The modules SGN. OBJ and TAN. OBJ are deleted from the library file 
TRAP. OB J on DT3:. 

* i... :i: :(•:< f :i: l ~ i... :i: b f :i: l / d > a b c / r > » e f 
mod name: 

FIRST <CR> 
<CR> 

The module FIRST. OBJ is deleted from the library (LIBFIL) j the module 
ABC. OBJ replaces an old module of the same name in the library, and 
the modules in the file DEF.OBJ are inserted into the library. 

*l.:i:bf:i:l==i...ibf : 'il../d 
mob name: 

X<CR> 
X <CR> 
<CR> 

Two modules of the same name are deleted from the library file LIBFIL 
(module names are assigned with the .TITLE statement as described in 
Section 7.2.1) . 



7.2.2.6 Delete Global Switch - The Delete Global switch gives the 
user the ability to delete a specific entry point from a library 
file's Entry Point Table. 

Command Format: 

*dev : lib=dev : lib/G 

where: 

dev: represents the device on which the library file 

exists 

lib represents the filename of an existing library 

file 
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/G represents the Delete Global switch; may be 

positioned anywhere on the input side of the 
command line 

When the /G switch is used, the Librarian prints : 

ENTRY POINT: 

The user should respond with the name of the entry point to be deleted 
followed by a carriage return; he may continue until all entry points 
to be deleted have been entered. Typing only a carriage return 
(either on a line by itself or immediately after the ENTRY POINT: 
message) terminates input and initiates execution of the command line. 

Example : 

#ROLL^ROLL/G 



ENTRY POINT J 
NAME A <CR> 
NAMEB <CR> 
<CR> 

This command instructs LIBR to delete the entry points NAMEA and NAMEB 
from the entry point table found in the library file ROLL., OBJ on DK:. 



Since entry pbints are bnly deleted from the Entry Point Table (and 
not from the library itself) whenever a library file is updated, all 
entry points that were previously deleted are restored unless the /G 
switch is again used to delete them. This feature allows the user to 
recover from inadvertently deleting the wrong entry point. 
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7.2.2.7 Update Switch - The Update switch allows the user to update a 
library file by combining the insert and replace functions. If the 
object modules included in an input file in the command line already 
exist in the library file, they are replaced; if not, they are 
inserted. (No error messages are printed when using the Update 
function as might occur under the Insert and Replace functions.) /U 
must follow each input file containing modules to be updated. 

Command Formats 

*dev : lib=dev : lib , dev : inputl/U , . . . , dev : inputn/U 

where; .-.-.'" ...;:■•.. 

dev; represents a device specification 

lib represents the filename of an existing library 

■■;■■■-■■■■■ .file- 

input represents the names of files containing object 
modules to be updated. 

/U represents the Update switch 
Examples; -,:>•■.--•-?-. - .... 

* b a l :i: b » b a i... :i: b ? f o l t / u > r a l t b a r t / u 

This command line instructs LIBR to Update the library file BALIB.OBJ 
on s ^he default device. First the modules r in FOLT.OBJ and BART. OBJ 
replace old modules of the same names 'in the library file, or if none 
already exist under their names, the modules are inserted. Then the 
modules from the file TAL.GBJ are-inserted; ah error message is 
printed if the name of the module in TAL.OBJ already exists. 

*XL.IB™XL JB/Di- Z./U/G 

MOD name: 
X <CR> 
X <CR> 
<CR> 

ENTRY POINT!: 
SEC <CR> 
SEC:l. <CR> 
<CR> 

There are two object modules of the same name (X) in both 7, and 
XLIB; -these are first deleted from XLIB. This ensures that both 
modules X in file Z are correctly placed into the library. Entry 
points SEC and SEC1 are also deleted from the Entry Point Table, 
but automatically return when the libary (XLIB) is updated. 



7.2.2.8 Listing the Directory of a Library File - The user may 
specify that a listing of the contents of a library file be output by 
indicating both the library file and a list file in the command line. 
Since a library file is not being created or updated, it is not 
necessary to Indicate the filename on the output side of the command 
line; however a comma must be used to designate a null output library 
file. 
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Command Formats: 

*,LP:=devslib 
or 

* ,dev : lis t=dev : lib 

where : 

dev: represents a device specification 

lib represents the file name of an existing library file 

LP: indicates the listing is to be sent directly to the 
line printer 

list represents a list file of the library file's contents 
Examples : 

*»dt2uj:st^l:i:bf:i:i... 

This command line outputs to DECtape 2 as LIST.LLD a listing of the 
contents of the library file LIBPIL.OBJ on the default device. 

*»i..p:==i-i..ib 

This command outputs on the line printer a listing of all modules in 
the library file PLIB.OBJ stored on the default device. Assuming this 
library is composed of modules STOP, WAIT, and IMUL, is 2 blocks long, 
was created on September 6, 1974, and the listing was requested on 
September 6, 1974, the directory format appears as follows j 



RT-ll 
PU8 


LIBRARIAN 


X02-03 
6. SEP. ?A 


6-5EP-74 
2 SLOCKS 




MODULE 




6MRY/GSECT 


ENTSY/CSECT 


ENTHY/CSECT 


STOP 
WAIT 
IMUL 




ST PS 
SwAJT 

MUISIS 
MylSSS 


MUISMS 
• MLI 


MUISPS 



7.2.2.9 Merging Library Files - Two or more library files may be 
merged under one filename by indicating all the library files to be 
merged in a single command line. The individual library files are not 
deleted following the merge. 

Command Format: 

*dev »lib=dev: input!, . . . ,dev:inputn 

where : 

dev: represents a device specification 

!it> represents the name of the library file which will 

contain all the merged files (if a library file 
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already exists under this name, it must also be 
indicated in the input side of the command line in 
order to be included in the merge) 

input represents the library files to be merged together 
Thus, the command: 

* m a :i: n ■■■■■■■■ m a :i: n » i r :i: g » s r p * b a c: 

combines library files MAIN. OBJ, TRIG. OBJ, STP.OBJ,,and BAC.OBJ under 
the existing library file name MAIN. OBJ; all files are on the default 
device DKs. 

#F"ORT : -A»B»C 

This command creates a library file named PORT. OBJ and merges existing 
library files A.OBJ, B.OBJ, and C.OBJ under the filename PORT. OBJ. 

NOTE 

Library files that have been combined 
under PIP are illegal as input to both 
the Librarian and the Linker. 



7.3 COMBINING LIBRARY SWITCH FUNCTIONS 

Two or more library functions may be requested in the same command 
line. The Librarian performs functions in the following order: 

1. /C 



2. 
3. 
4. 
5. 
6. 


/D 
/G 

/u 

/R 
Insertions 


7. 


Listing 


Example : 





*f:i:l.e , i...p : ==f:i:le/d > mgdx * mody/r 



MOD NAME J 
XYZ<CR> 
A <CR> 
<CR> 



Functions in this example are performed in order , as follows : 

1. Delete modules XYZ.OBJ and A.OBJ from the library file 
FILE. OB J 

2. Replace any duplicate of the module in the file MODY.OBJ 

3. Insert the modules in the file MODX.OBJ 

4. List the contents of FILE. OBJ on the line printer 
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7.4 FORMAT OF LIBRARY FILES 



A library file is a contiguous file consisting of a header, an Entry 
Point Table (library directory) and one or more library object 
modules, as illustrated in Figure 7-1: 



LIBRARY HEADER 



ENTRY POINT TABLE 



OBJECT MODULES 



LIBRARY END TRAILER BLOCK 



Figure 7-1 
General Library File Format 



The following paragraphs describe in detail each component of a 
library file. 



7.4.1 Library Header 

The header section of a library file contains 17 (decimal) words which 
describe the current status of the file (refer to Figure 7-2). This 
includes information relating to the version of the Librarian in use, 
the date and time of file creation or update, the relative starting 
address of the Entry Point Table (EPT) , the number of EPT entries 
available and in use, and the placing of the next module to be 
inserted into the library file. The contents of the library header 
are updated as the library file is modified, so that LIBR can always 
quickly and easily access the information it needs to perform its 
functions. Figure 7-2 illustrates the header format. 
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1 


\ FORMATTED BINARY 


5*8 




7 


LIBRARIAN CODE 


X. 


VERSION NUMBER 





RESERVED 


X 


YEAR-MONTH-DAY 


. ■ ," . . . ; 


~\ 












\ RESERVED 


— 






J 


I2« 


EPT RELATIVE START ADDRES5 ;_' 




XI 


EPT ENTRIES ALLOCATED IN BYTES 


is,: ■. •; jo 


EPT ENTRIES AVAILABLE (NOT USSO IN- VERSION 1.) 


.) ■ ; ,S-"--x2": 


NEXT INSERT RELATIVE BLOCK f NUMBER "" - r ' 


X3 


NEXT BYTE WITHIN BLOC* " ■'■ ; ' "'■' 


° 


NOT USED (MUST BE ZERO) 



Figure 7-2 
Library Header Format 



7.4.2 Entry Point Table (Library; Directory) 

The Entry Point Table is .located immediately after the library header. 
It is composed of four-word entries which include the names, 
addresses, and entry points of all object modules in the library file. 
The first two words of an entry in the EPT contain the Radix 50 name 

by which an entry point, CSECT, or module is referenced. The third 
word provides a pointer to the; object, module where an entry point is 
defined. The fourth word contains the total number of CSECTs in the 
object module (information needed by the Linker) , and the relative 
byte within the block pointing to the object module's starting point, 
as . shown in Figure 7-3. 



SYMBOL {RAD 50) 



SYMBOL (RAD 50) 



ADDRESS OF BLOCK 



# OF CSECTS IN 
OBJECT MODULE 



RELATIVE BYTE IN BLOCK 



BIT15=l-MODULE NAME 

■- »-CSECT OR ENTRY POINT NAME I 
RELATIVE BYTE MAXIMUM* 777 8 
CSECTS MAXIMUM =177 



Figure 7-3 
Format of Entry Point Table 
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7.4.3 Object Modules 



An object module 
a global symbol 



Object modules follow the Entry Point Table, 
consists of three main types of data blocks : 

directory, text blocks, and a relocation directory. The information 
contained in these data blocks is used by the Linker during creation 
of a load module. 



7.4.4 Library End Trailer 

Following all object modules in a library file is a specially coded 
library end trailer which signifies the end of the file. This trailer 
is illustrated in Figure 7-4. 



10 



10 



357 



FORMATTED BINARY HEADER 
FORMATTED BINARY LENGTH 
TYPE CODE 

NOT USED (MUST BE ZERO) 
CHECKSUM BYTE 



Figure 7-4 
Library End Trailer 



7.5 LIBR ERROR MESSAGES 

The following error messages are printed following incorrect use of 
LIBR? if any errors result during library processing, the user must 
reenter the command. 



Message 
?BAD LIBR? 



?BAD OBJ? 



?CSECT ERROR? 



Meaning 

The user has attempted to build a 

library file containing no directory 

entries or he has given an illegally 

constructed library file to the 
Librarian as input. 

A bad object module was detected during 
input . 

The user has extended beyond the 
allowable .CSECT space for an object 
module to be placed in the library 
(i.e., the object module contains 
greater than 127(decimal) .CSECTs) . 
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Message 



Meaning 



?DEV FULL? 



The device is full; LIBR is unable to 
create or update the indicated library 
file. The CSI prints an asterisk and 
waits for the user to enter another 
command line. 



?FIL NOT FND? 



One of the input files indicated in the 
command line was not found. The CSI 
prints an asterisk; the command may be 
reentered. 



?ILL CMD? 



xxxxxx ILL DEL 



An illegal command was used in the 
command line. The CSI prints an 
asterisk; the command may be reentered. 

An attempt was made to delete from the 
library's directory a module or an entry 
point that does not exist; xxxxxx 

represents the module or entry point 
name. The name is ignored and processing 
continues. 



?ILL DEV? 



xxxxxx ILL INS 



xxxxxx ILL REPL 



PIN ERR? 



?LIBR FIL ILL REPL? 



?N0 CORE? 



?OUT ERR? 



An illegal device was specified in the 
command line. The CSI prints an 
asterisk; the command may be reentered. 

An attempt was made to insert a module 
into a library which contains the same 
entry point as an existing module, 
xxxxxx represents the entry point name. 
The entry point is ignored but the module 
is still inserted into the library. 

An attempt was made to replace in the 
library file a module which does not 
already exist. xxxxxx represents the 

module name. The module is ignored and 
the library is built without it. 

An unrecoverable hardware/software error 
has occurred while processing an input 
file. The CSI prints an asterisk and 
waits for another command to be entered. 

The user has specified that a library 
file be replaced by another library 
file. Only object modules can be 
replaced. 

Available free memory has been used up. 
The current command is aborted and the 
CSI prints an asterisk; a new command 
may be entered. 

An unrecoverable hardware/software error 

has occurred while processing an output 
file. This may indicate that there is 
not enough space left on the device to 
create the library file, even though 
there may be enough directory entries. 
The CSI prints an asterisk and waits for 
the user to enter another command. 
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CHAPTER 8 
ON-LINE DEBUGGING TECHNIQUE 



RT-11 On-line Debugging Technique (ODT) is a system program that aids 
in debugging assembled and linked object programs. From the keyboard, 
the user interacts with ODT and the object program to: 

1. Print the contents of any location for examination or 
alteration. 

2. Run all or any portion of an object program using the 
breakpoint feature. 

3. Search the object program for specific bit patterns. 

4. Search the object program for words which reference a 
specific word. 

5. Calculate offsets for relative addresses. 

6. Fill a single word, block of words, byte or block of bytes 
with a designated value. 

The assembly listing of the program to be debugged should be readily 
available when ODT is being used. Minor corrections to the program 
can be made on-line during the debugging session, and the program may 
then be run under control of ODT to verify any changes made. Major 
corrections, however (such as a missing subroutine), should be noted 
on the assembly listing and incorporated in a subsequent updated 
program assembly. 



8.1 CALLING AND USING ODT 

ODT is supplied as a relocatable object module. It can be linked with 
the user program (using the RT-11 Linker) for an absolute area in 

memory and loaded with the user program. When linked with the user 
program, ODT should reside in low memory, starting at 1000, to accom- 
modate its stack. 

Once loaded in memory with the user program, ODT has three legal start 
or restart addresses. The lowest (O.ODT) is used for normal entry, 
retaining the current breakpoints. The next (O.ODT+2) is a restart 
address which clears all breakpoints and re-initializes ODT saving the 
general registers and clearing the relocation registers. The last 
address (O.ODT+4) is used to reenter ODT. A reenter saves the 
Processor Status and general registers and removes the breakpoint 
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instructions from the user program. ODT prints the Bad Entry (BE) 
error message. Breakpoints which were set are reset on the next ;G 
command. (;P is illegal after a BE message.) The ;G and ;P commands 
are used to run a program and are explained in Section 8.3.7. 

The absolute address used is the address of the entry point O.ODT 
shown in the Linker load map. O.ODT is always the lowest address of 
ODT+172, i.e., O.ODT is relative location 172 in ODT. 

NOTE 

If linked with an overlay structured 
file, ODT should reside in the root 
segment so it is always in memory. A 
breakpoint inserted in an overlay will 
be destroyed if it is overlaid during 
program execution. 

If ODT is being used in a Foreground/Background environment with 
another job running, ODT's priority bit must be set to as follows: 

*$P/ B80B07 6 <CR> 

This puts ODT into the wait state at level 0, not 7. If this is not 
done, all interrupts (including clock) will be locked out while ODT is 
waiting for terminal input. 

Examples : 

1. ODT Linked with the User Program: 

^GET USER. SftV User program previously linked to 

ODT is brought into memory. 
^ START 1172 Value (1172) of entry point O.ODT 

(determined from Linker load map) 

°JLL V01 ' ei is used to start ODT. 

* 

2. Loading ODT with the User Program: 

.GET ODT. SnV ODT is loaded into memory. 

.GET USER. SfiV User program is loaded into memory. 

STftffT 49172 Assuming ODT has been linked for a 

bottom address of 40000, ODT starts. 

D T v 31-32 



3. Restarting ODT Clearing Breakpoints: 

START 1174 Assuming ODT was originally 

~ linked for a bottom address of 1000, 

* this command (O.ODT+2) 

- re-initializes ODT and clears any 

previous breakpoints. 
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4. Reentering ODT: 

START 1176 Assuming ODT was linked for a 

bottom address of 1000, the value 
BE691212 of O.ODT 1172+4 is used as the 

* start address. 

5. Using ODT with Foreground/Background Jobs: 

It is possible to use ODT to debug programs written as either 
background or foreground jobs. In the background or under 
the Single- Job Monitor, ODT can be linked with the program as 
described in Example 1 above. 

To debug a program in the foreground area, it is recommended 
that ODT be run in the background while the program to be 
debugged is in the foreground. The sequence of commands to 
do this is : 

^FRUN PROG/P Load the foreground program. 
LORDED RT xxxxxx The first address of the job is 
^ RUN ODT printed (xxxxxx) 

Run ODT in the background 
OPT V81-81 and set a relocation register 
*xxxxxx, BR to the start of the job. $F 
*$F,'686688 8<CR> is the format register. It 
*0< G should be cleared to enable proper 

address print out. 0;G starts the 
i RSU Keyboard Monitor again, and .RSU 

starts the foreground job. 

The copy of ODT used must be linked low enough so that it 
will fit in memory along with the foreground job. 

NOTE 

Since ODT uses its own terminal handler, 
it cannot be used with the display 
hardware. If GT ON has been typed, ODT 
will ignore it and direct I/O only to 
the console terminal. 



8.1.1 Return to Monitor, CTRL C 

If ODT is awaiting a command, a CTRL C from the keyboard calls the 

RT-11 Keyboard Monitor. The monitor responds with a tC on the 
terminal and awaits a Keyboard Monitor command. (The monitor REENTER 

command may be used to reenter ODT only if the user program has set 

the reenter bit. Otherwise ODT is reentered at address O.ODT+4 as 
shown above.) 
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8.1.2 Terminate Search, CTRL U 



If typed during a search printout, a C XL U terminates the search and 
ODT prints an asterisk. 



8.2 RELOCATION 

When the assembler produces a binary object module, the base address 
of the module is taken to be location 000000, and the addresses of all 
program locations as shown in the assembly listing are indicated 
relative to this base address. After the module is linked by the 
Linker, many values within the program, and all the addresses of 
locations in the program, will be incremented by a constant whose 
value is the actual absolute base address of the module after it has 
been relocated. This constant is called the relocation bias for the 
module. Since a linked program may contain several relocated modules 
each with its own relocation bias, and since, in the process of 
debugging, these biases will have to be subtracted from absolute 
addresses continually in order to relate relocated code to assembly 
listings, RT-11 ODT provides an automatic relocation facility. 

The basis of the relocation facility lies in eight relocation 
registers, numbered through 7, which may be set to the values of the 
relocation biases at different times during debugging. Relocation 
biases should be obtained by consulting the memory map produced by the 
Linker. Once set, a relocation register is used by ODT to relate 
relocatable code to relocated code. For more information on the exact 
nature of the relocation process, consult Chapter 6, the RT-11 Linker. 



8.2.1 Relocatable Expressions 

A relocatable expression is evaluated by ODT as a 16-bit (6-digit 
octal) number and may be typed in any one of the three forms presented 
in Table 8-1. In this table, the symbol n stands for an integer in the 
range to 7 inclusive, and the symbol k stands for an octal number up 
to six digits long, with a maximum value of 177777. If more than six 
digits are typed, ODT takes the last six digits, truncated to the 
low-order 16 bits, k may be preceded by a minus sign, in which case 
its value is the two's complement of the number typed. For example: 

k (number typed) Values 

1 000001 

-1 177777 

400 000400 

-177730 000050 

1234567 034567 
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Table 8-1 
Forms of Relocatable Expressions (r) 





r 


Value of r 


A) 
B) 

C) 


k 
n,k 

C or 
C,k or 

n,C or 
C,C 


The value of r is simply the value of k. 

The value of r is the value of k plus 
the contents of relocation register n. 
If the n part of this expression is 
greater than 7, ODT uses only the last 
octal digit of n. 

Whenever the letter C is typed, ODT 
replaces C with the contents of a 
special register called the Constant 
Register. This value has the same role 
as the k or n that it replaces (i.e., 
when used in place 01 n it designates a 
relocation register) . The Constant 
Register is designated by the symbol $C 
and may be set to any value, as 
indicated below. 



In the following examples, assume in each case that relocation 
register 3 contains 00 3400 and that the constant register contains 
000003. 



5;C 

-17, -C 

3,0;C 

3,150;C 

3,-l;C 

C;C 

3,C;C 

C,0;C 

C,10;C 

C,C;C 



Value of r 

000005 
177761 
003400 
003550 
003377 
000003 
003403 
003400 
003410 
003403 



NOTE 

For simplicity most examples in this 
section use Form A. All three forms of r 
are equally acceptable, however. 

8.3 COMMANDS AND FUNCTIONS 

When ODT is started (as explained in Section 8.1) it indicates 
readiness to accept commands by printing an asterisk on the left 
margin of the terminal page. Most of the ODT commands can be issued 
in response to the asterisk. For example, a word can be examined and 
changed if desired, the object program can be run in its entirety or 
in segments, or memory can be searched for certain words or references 
to certain words. The discussion 'below explains these features. In 
the following examples, characters output by ODT are underlined to 
differentiate from user input. 

8.3.1 Printout Formats 

Normally, when ODT prints addresses (as with the commands +, t, <-, @, 
<, and >) it attempts to print them in relative form (Form B in Table 



8-5 



On-Line Debugging Technique 

8-1) . ODT looks for the relocation register whose value is closest but 
less than or equal to the address to be printed, and then represents 
the address relative to the contents of the relocation register. 
However, if no relocation register fits the requirement, the address 
is printed in absolute form. Since the relocation registers are 
initialized to -1 (the highest number) the addresses are initially 
printed in absolute form. If any relocation register subsequently has 
its contents changed, it may then, depending on the command, qualify 
for relative form. 

For example, suppose relocation registers 1 and 2 contain 1000 and 
1004 respectively, and all other relocation registers contain numbers 
much higher. Then the following sequence might occur (the slash 
command causes the contents of the location to be printed; the line 
feed command (<LF>) accesses the next sequential location) : 

* 7 74/ 886060 <LF> 

eaa rrs /o 8 6 668 <lf> 

1,666 666 /88 8B86 <LF> (absolute location 1000) 
1,666662 ,■'6666 86 <LF> (absolute location 1002) 
2, 868666 ?6~66886 (absolute location 1004) 

The printout format is controlled by the format register, $F. Normally 
this register contains 0, in which case ODT prints addresses 
relatively whenever possible. $F may be opened and changed to a 
non-zero value, however, in which case all addresses will be printed 
in absolute form (see paragraph 8.3.4, Accessing Internal Registers). 



8.3.2 Opening, Changing, and Closing Locations 

An open location is one whose contents ODT prints for examination, 

making those contents available for change. In a closed location, the 

contents are no longer available for change. Several commands are 
used for opening and closing locations. 

Any command used to open a location when another location is already 
open causes the currently open location to be closed. The contents of 
an open location may be changed by typing the new contents followed by 
a single-character command which requires no argument (i.e., <LF> , t, 
RETURN, <-,<§,>,<). 



The Slash, / 

One way to open a location is to type its address followed by a slash: 

+ 1000/0JL2746 

Location 1000 is open for examination and is available for change. 

If the contents of an open location are not to be changed, type the 
RETURN key and the location is closed; ODT prints an asterisk and 
waits for another command. However, to change the word, simply type 
the new contents before giving a command to close the location: 

*1690/ 612746 012345 <CR> 
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In the example above, location 1000 now contains 012345 and is closed 
since the RETURN key was typed after entering the new contents, as 
indicated by ODT's second asterisk. 

Used alone, the slash reopens the last location opened: 

*1B0B/ 612345 2340 <CR> 
*/ BB234B 

In the example above, the open location was closed by typing the 
RETURN key. ODT changed the contents of location 1000 to 002340 and 
then closed the location before printing the *. The single slash 
command directed ODT to reopen the last location opened. This allowed 
verification that the word 002340 was correctly stored in location 
1,000. 

Note again, that opening a location while another is open 
automatically closes the currently open location before opening the 
new location. 

Also note that if an odd numbered address is specified with a slash, 
ODT opens the location as a byte, and subsequently behaves as if a 
backslash had been typed (see the following paragraph) . 



The Backslash, \ 



In addition to operating on words, ODT operates on bytes. One way to 
open a byte is to type the address of the byte followed by a 
backslash. (On the LT33 or LT35 terminal \ is typed by pressing the 
SHIFT key while typing the L key.) This causes not only the printing 
of the byte value at the specified address but also the interpreting 
of the value as ASCII code, and the printing of the corresponding 
character (if possible) on the terminal: 

*1001\101_=R 

A backslash typed alone reopens the last open byte. If a word was 
previously open, the backslash reopens its even byte: 

*1002/600004 S004 = 



The LINE FEED Key,<LF> 

If the LINE FEED key is typed when a location is open, ODT closes the 
open location and opens the next sequential location: 

*1000/002_340 <LF> ( <LF> denotes typing the LINE FEED key) 

691B82 ,-'012746 

In this example, the LINE FEED key caused ODT to print the address of 
the next location along with its contents, and to wait for further 
instructions. After the above operation, location 1000 is closed and 
1002 is open. The open location may be modified by typing the new 
contents . 

If a byte location was open, typing the LINE FEED key opens the next 
byte location. 
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T he Up- Arrow, t or A 

If the up-arrow (or circumflex) is typed when a location is open 
(up-arrow is produced on an LT33 or LT35 by typing SHIFT N) , ODT closes 
the open location and opens the previous location. To continue from 
the example above: 

*881882/ 81274B f 
9O1BB0 /66234B 

Now location 1002 is closed and 1000 is open. The open location may 
be modified by typing the new contents. 

If the opened location was a byte, then up-arrow opens the previous 
byte. 



The Back- Arrow, *- or 



If the back-arrow (or underline) is typed (via SHIFT on an LT33 or 
LT35 terminal) to an open word, ODT interprets the contents of the 
currently open word as an address indexed by the Program Counter (PC) 
and opens the addressed location: 

+1086/800006 <- 



BB1616 /B0B495 

Notice in this example that the open location, 1006, was indexed by 
the PC as if it were the operand of an instruction with address mode 
67 as explained in Chapter 5. 

A modification to the opened location can be made before a line feed, 
up-arrow, or back-arrow is typed. Also, the new contents of the 
location will be used for address calculations using the back-arrow 
command. Example: 

♦1 a8/ BB622 £ 4 <LF> (modify to 4 and open next location) 
888162 /686111 6f (modify to 6 and open previous location) 
8B8188 /668664 lSS-t- (change to 100 and open location indexed 
80B202 ,'123456 by PC) 



Open the Addressed Location, @ 



The at symbol @ (SHIFT P on the LT33 or LT35 terminal) may be used to 

optionally modify a location, close it, and then use its contents as 
the address of the location to open next. 

*1886/ 801044 e (open location 1044 next) 

881844 ,-'808 580 

♦1886/ 881644 21886 (modify to 2100 and open location 
88216B ,'88616? 2100) 
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R elative Branch Offset , > 

The right-angle bracket, >, will optionally modify a location, close 
it, and then use its low-order byte as a relative branch offset to the 
next word to be opened. For example: 

*1 B 3 2 / 68 6 4 6 ? 3 8 1 > (modify to 301 and interpret as a 
668636 , J 880@18 relative branch) 

Note that 301 is a negative offset (-77) . The offset is doubled before 
it is added to the PC; therefore, 1034+(-176)=636. 



Return to Previous Sequence, < 

The left-angle bracket, <, allows the user to optionally modify a 
location, close it, and then open the next location of the previous 
sequence which was interrupted by a back-arrow, §, or right-angle 
bracket command. Note that back-arrow, 9, or right-angle bracket 
causes a sequence change to the word opened. If a sequence change has 
not occurred, the left-angle bracket simply opens the next location as 
a LINE FEED does. This command operates on both words and bytes. 

* 1 8 3 £ / 868487 381 > (> causes a sequence change) 
8886 3 6 / 8886 18 < (return to original sequence) 
661834 ,■' 8 616 4 8 @ (@ causes a sequence change) 

861648 ,-'866485 \ 665 = < (< now operates on byte) 
861835 S 862 = <: ' (< acts like <LF» 
881836 S004 = 



8.3.3 Accessing General Registers 0-7 

The program's general registers 0-7 are opened with a command in the 
following format; 

*$n/ 

where n is the integer representing the desired register (in the range 
through 7) . When opened, these registers can be examined or changed 
by typing in new data as with any addressable location. For example: 

*»8/ B68833 <CR> (R0 was examined and closed) 

i 

**4,'886474_464<CR> (R4 was opened, changed, and closed) 

* 

The example above can be verified by typing a slash in response to 
ODT's asterisk: 

*/ 6B6464 

The LINE FEED, up-arrow, back-arrow or @ command may be used when a 
register is open. 
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8.3.4 Accessing Internal Registers 

The program's Status Register contains the condition codes of the most 
recent operational results and the interrupt priority level of the 
object program. It is opened by typing $S. For example: 

*<S,' QBaill 

$S represents the address of the Status Register. In response to $S 

in the example above, ODT printed the 16-bit word, of which only the 
low-order eight bits are meaningful. Bits 0-3 indicate whether a 

carry, overflow, zero, or negative (in that order) has resulted, and 

bits 5-7 indicate the interrupt priority level (in the range 0-7) of 

the object program. (Refer to the PDP-11 Processor Handbook for the 
Status Register format.) 

The $ is used to open certain other internal locations listed in Table 
8-2: 

Table 8-2 
Internal Registers 



Register 


Function 


$B 


location of the first word of the breakpoint table 
(see Section 8.3.6). 


$M 


mask location for specifying which bits are to be 
examined during a bit pattern search (see Section 
8.3.9). 


$P 


location defining the operating priority of ODT 
(see Section 8.3.15). 


$S 


location containing the condition codes (bits 0-3) 
and interrupt priority level (bits 5-7) (explained 
above) . 


$c 


location of the Constant Register (see Section 
8.3.10). 


$R 


location of Relocation Register 0, the base of the 
Relocation Register table (see Section 8.3.13). 


$F 


location of Format Register (see Section 8.3.1). 



8.3.5 Radix 50 Mode, X 



The Radix 50 mode of packing certain ASCII characters three to a word 
is employed by many DEC-supplied PDP-11 system programs, and may be 
employed by any programmer via the MACRO Assembler's ".RAD50 M 
directive. ODT provides a method for examining and changing memory 
words packed in this way with the X command. 

When a word is opened and the X command is typed, ODT converts the 
contents of the opened word to its 3-character Radix 50 equivalent and 
prints these characters on the terminal. One of the responses in 
Table 8-3 can then be typed: 
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Table 8-3 
Radix 50 Terminators 



Response 



Effect 



RETURN key <CR> 
LINE FEED key <LF> 

t key 



Any three 
characters whose 
octal code is 040 
(space) or greater. 



Closes the currently open location. 

Closes the currently open location and 
opens the next one in sequence. 

Closes the currently open location and 
opens the previous one in sequence. 

Converts the three specified characters 
into packed Radix 50 format. 



Legal Radix 50 characters for this last response are: 



Space 



through 9 



A through Z 



If any other characters are typed, the resulting binary number is 
unspecified (that is, no error message is printed and the result is 
unpredictable) . Exactly three characters must be typed before ODT 
resumes its normal mode of operation. After the third character is 
typed, the resulting binary number is available to be stored in the 
opened location by closing the location in any one of the ways listed 
in Table 8-3. Example: 

*1800/ 842421 X^KBI_CBfl <CR > 
+ 1000,'011421 X = CBR 



NOTE 

After ODT has converted the three 
characters to binary, the binary number 
can be interpreted in one of many 
different ways, depending on the command 
which follows. For example: 

* 1 2 3 4 ,' 863337 X = PR0 X I T / £12704 

Since the Radix 50 equivalent of XIT is 
113574, the final slash in the example 
will cause ODT to open location 113574 
if it is a legal address. (Refer to 
paragraph 8.5 for a discussion of 
command legality and detection of 
errors . ) 



8.3.6 Breakpoints 

The breakpoint feature facilitates monitoring the progress of program 
execution. A breakpoint may be set at any instruction which is not 
referenced by the program for data. When a breakpoint is set, ODT 
replaces the contents of the breakpoint location with a trap 
instruction so that program execution is suspended when a breakpoint 
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is encountered. The original contents of the breakpoint location are 
restored, and ODT regains control. 

With ODT, up to eight breakpoints, numbered through 7, can be set at 
any one time. A breakpoint is set by typing the address of the 
desired location of the breakpoint followed by ;B. Thus r;B sets the 
next available breakpoint at location r. (If all 8 breakpoints have 
been set, ODT ignores the r;B command.) Specific breakpoints may be 
set or changed by the r;nB command where n is the number of the 
breakpoint. For example: 

*1020' B (sets breakpoint 0) 

*1038; B (sets breakpoint 1) 

*104i3;B (sets breakpoint 2) 

*1832;1B (resets breakpoint 1) 

* 

The ;B command removes all breakpoints. Use the ;nB command to remove 
only one of the breakpoints, where n is the number of the breakpoint. 
For example: 

*; 2B (removes the second breakpoint) 

* 

A table of breakpoints is kept by ODT and may be accessed by the user. 
The $B/ command opens the location containing the address of 
breakpoint 0. The next seven locations contain the addresses of the 
other breakpoints in order, and can be sequentially opened using the 
LINE FEED key. For example: 

*$B,'061020 <LF> 

nnnnnn ,'80.1 8 32 <LF> 

nnnnnn / nnnnnn (nnnnnn=address internal to ODT) 

In this example, breakpoint 2 is not set. The contents printed is an 
address internal to ODT and can be determined by checking the Linker 
Load Map (see Chapter 6). 

It should be noted that a repeat count in a Proceed command refers 
only to the breakpoint that has most recently occurred. Execution of 
other breakpoints encountered is determined by their own repeat 
counts . 



8.3.7 Running the Program, r;G and r;P 

Program execution is under control of ODT. There are two commands for 
running the program: r;G and r;P. The r;G command is used to start 
execution (Go) and r;P to continue (Proceed) execution after halting 
at a breakpoint. For example: 

Execution is started at location 1000. The program runs until a 
breakpoint is encountered or until program completion, unless it gets 
caught in an infinite loop, in which case it must be either restarted 
or reentered as explained in Section 8.1. 

Upon execution of either the r;G or r;P command, the general registers 
0-6 are set to the values in the locations specified as $0-$6 and the 
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processor Status Register is set to the value in the 
specified as $S. 



location 



When a breakpoint is encountered, execution stops and ODT prints Bn; 
(where n is the breakpoint number) , followed by the address of the 
breakpoint. Locations can then be examined for expected data. For 

example: 



*1019; 3B 
*10@0; Q 
B3; 091010 
# 



(breakpoint 3 is set at location 1010) 
(execution started at location 1000) 
(execution stopped at location 1010) 



To continue program execution from the breakpoint, type ;P in response 
to ODT's last *. 

When a breakpoint is set in a loop, it may be desirable to allow the 
program to execute a certain number of times through the loop before 
recognizing the breakpoint. This can be done by setting a proceed 
count using the k;P command; this command specifies the number of 
times the breakpoint is to be encountered before program execution is 
suspended (on the kth encounter). The count, k, refers only to the 
numbered breakpoint which most recently occurred. A different proceed 
count may be specified for the breakpoint when it is encountered. 
Thus: 



B3; 091010 
*1026; 2B 
*4i P 
B2j 001026 



(execution halted at breakpoint 3) 
(reset breakpoint 3 at location 1026) 
(set proceed count to 4 and 
continue execution; loop through 
- breakpoint three times and halt on 

fourth occurrence of the breakpoint) 

Following the table of breakpoints (as explained in Section 8.3.6) is 
a table of proceed command repeat counts for each breakpoint. These 
repeat counts can be inspected by typing $B/ and nine LINE FEEDs. The 
repeat count for breakpoint is printed (the first seven LINE FEEDs 
cause the table of breakpoints to be printed; the eighth types the 
single instruction mode, explained in the next section, and the ninth 
LINE FEED begins the table of proceed command repeat counts). The 
repeat counts for breakpoints 1 through 7, and the repeat count for 
the single-instruction trap follow in sequence. Before a proceed 
count is assigned a value by the user, it is set to 0; after the count 
has been executed, it is set to -1. Opening any one of these provides 
an alternative way of changing the count as the location, once open, 
can have its contents modified in the usual manner by typing the new 
contents and then the RETURN key. For example: 



nnnnnn /BO 1636 <LF> 

nnnnnn / 866 6 36 <LF> 

nnnnnn / 860688 15 <LF> 

nnnnnn /eeeeee <LF> 



(address of breakpoint 7) 

(single instruction address) 

(count for breakpoint 0; change to 15) 

(count for breakpoint 1) 



nnnnnn ,'6666 68 . <LF> 
nnnnnn /nnnnnn 



(count for breakpoint 7) 

(repeat count for single instruction 

mode; the single instrucion address 
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is an address internal to the user 
program if single instrucion mode is 
used) 

The address indicated as the single instruction address and the repeat 
count for single instruction mode are explained next. 



8.3.8 Single Instruction Mode 

with this mode the number of instructions to be executed before 
suspension of the program run can be specified. The Proceed command, 
instead of specifying a repeat count for a breakpoint encounter, 
specifies the number of succeeding instructions to be executed. Note 
that breakpoints are disabled when single instruction mode is 
operative. 



Commands for single instruction mode are: 



;nS 



n;P 



;S 



Enables single instruction mode (n can have any 
non-zero value and serves only to distinguish this 
form from the form ;S) . Breakpoints are disabled. 

Proceeds with program run for next n instructions 
before reentering ODT (if n is missing, it is 
assumed to be 1) . Trap instructions and associated 
handlers can affect the Proceed repeat count. See 
Section 8.4.2. 

Disables single instruction mode. 



When the repeat count for single instruction mode is exhausted and the 
program suspends execution, ODT prints: 

B8;nnnnnn 

where nnnnnn is the address of the next instruction to be executed. 

The $B breakpoint table contains this address following that of 

breakpoint 7. However, unlike the table entries for breakpoints 0-7, 
direct modification has no effect. 

Similarly, following the repeat count for breakpoint 7 is the repeat 
count for single instruction mode. This table entry may be directly 
modified and thus is an alternative way of setting the 
single-instruction mode repeat count. In such a case, ;P implies the 
argument set in the $B repeat count table rather than an assumed 1. 



8.3.9 Searches 

With ODT all or any specified portion of memory can be searched for 
any specific bit pattern or for references to a particular location. 



8-14 



On-Line Debugging Technique 

Word Search, r;W 

Before initiating a word search, the mask and search limits must be 
specified. The location represented by $M is used to specify the mask 
of the search. $M/ opens the mask register. The next two sequential 
locations (opened by LINE FEEDs) contain the lower and upper limits of 
the search. Bits set to 1 in the mask are examined during the search; 
other bits are ignored. Then the search object and the initiating 
command are given using the r;W command where r is the search object. 
When a match is found, (i.e., each bit set to 1 in the search object 
is set to 1 in the word being searched over the mask range) the 
matching word is printed. For example: 

*$H/ 888B88 17740S <LF> (test high-order eight bits) 
nnnnnn ,'800000 100s <LF> (set low address limit) 
nnnnnn /008888 1848 <CR> (set high address limit) 
*400, W (initiate word search) 

881010 /880770 
601024 ,"'080484 
* 

In the above example, nnnnnn is an address internal to ODT; this 
location varies and is meaningful only for reference purposes. In the 
first line above, the slash was used to open $M which now contains 
177400; the LINE FEEDs opened the next two sequential locations which 
now contain the upper and lower limits of the search. 

In the search process an exclusive OR (XOR) is performed with the word 
currently being examined and the search object, and the result is 
ANDed to the mask. If this result is zero, a match has been found and 
is reported on the terminal. Note that if the mask is zero, all 
locations within the limits are printed. 

Typing CTRL U during a search printout terminates the search. 



Effective Address Search, r;E 

ODT provides a search for words which address a specified location. 
Open the mask register only to gain access to the low and high limit 
registers. After specifying the search limits (as explained for the 
word search) , type the command r;E (where r is the effective address) 
to initiate the search. 

Words which are either an absolute address (argument r itself) , a 
relative address offset, or a relative branch to the effective 
address, are printed after their addresses. For example: 

*«M,M774aB <LF> (open mask register only to gain 

nnnnnn / , 69188B 1618 <LF> access to search limits) 

nnnnnn ^881848 i860 <CR> 

*1834; E (initiating search) 

081B16 /881886 (relative branch) 

001054 Z002767 (relative branch) 

*1820; E (initiating a new search) 

891822 f'177774 (relative address offset) 

881838 ^881028 (absolute address) 



8-15 



On-Line Debugging Technique 

Particular attention should be given to the reported effective address 
references because a word may have the specified bit pattern of an 
effective address without actually being so used. ODT reports all 
possible references whether they are actually used as such or not. 

Typing CTRL U during a search printout terminates the search. 



8.3.10 The Constant Register, r;C 

It is often desirable to convert a relocatable address into its value 
after relocation or to convert a number into its two's complement, and 
then to store the converted value into one or more places in a 
program. The Constant Register provides a means of accomplishing this 
and other useful functions. 

When r;C is typed, the relocatable expression r is evaluated to its 
6-digit octal value and is both printed on the terminal and stored in 
the Constant Register. The contents of the Constant Register may be 
invoked in subsequent relocatable expressions by typing the letter C. 
Examples follow: 

4-4432; C =173346 (the two's complement of 4432 is placed 

in the Constant Register) 

»6b32/ 062?Bl _ C <CR> (the contents of the Constant Register 

are stored in location 66 32) 

+1090; 1R (relocation Register 1 is set to 1000) 

*1, 4272; C =00527 2 (relative location 4272 is resprinted as 

an absolute location and stored in the 
Constant Register) 



8.3.11 Memory Block Initialization, ;F and ;I 

The Constant Register can be used in conjunction with the commands ;F 
and ;I to set a block of memory to a given value. While the most 
common value required is zero, other possibilities are plus one, minus 
one, ASCII space, etc. 

When the command ;F is typed, ODT stores the contents of the Constant 
Register in successive memory words starting at the memory word 
address specified in the lower search limit, and ending with the 
address specified in the upper search limit. 

When the command ;I is typed, the low-order 8 bits in the Constant 
Register are stored in successive bytes of memory starting at the byte 
address specified in the lower search limit and ending with the byte 
address specified in the upper search limit. 

For example, assume relocation register 1 contains 7000, 2 contains 
10000, and 3 contains 15000. The following sequence sets word 
locations 7000-7776 to zero, and byte locations 10000-14777 to ASCII 
spaces. 
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(open mask register to gain access 
*gM/ 886680 <LF> to search limits) 

nnnnnn ,'668866 1. 8 LF> (set lower limit to 7000) 
nnnnnn ,-'868898 2,-2 <LF> (set upper limit to 7776) 
*8; c = 8 80686 (Constant Register set to zero) 

*. F (Locations 7000-7776 set to zero) 

*$H/ 686688 <LF> 

nnnnnn/ 6 6 7 6 8 6 2,6 <LF> (set lower limit to 10000) 
nnnnnny86 77 76 3, -1 <CR> (set upper limit to 14777) 
*40; 0=080040 (Constant Register set to 40 

*; I (SPACE)) 

* (Byte locations 10000-14777 are set 

to value in low-order 8 bits of 
Constant Register) 



8.3.12 Calculating Offsets, r;0 

Relative addressing and branching involve the use of an offset — the 
number of words or bytes forward or backward from the current location 
to the effective address. During the debugging session it may be 
necessary to change a relative address or branch reference by 
replacing one instruction offset with another. ODT calculates the 
offsets in response to the r;0 command. 

The command r;0 causes ODT to print the 16-bit and 8-bit offsets from 
the currently open location to address r. For example: 

*346r-' 8B0SS4 4 14; Q 806844 622 22 <CR> 
*/ 000022 

In the example, location 346 is opened and the offsets from that 
location to location 414 are calculated and printed. The contents of 
location 346 are then changed to 22 (the 8-bit offset) and verified on 
the next line. 

The 8-bit offset is printed only if it is in the range -128 (decimal) 
to 127 (decimal) and the 16-bit offset is even, as was the case above. 
For example, the offset of a relative branch is calculated and 
modified as follows: 

*1634,-' 183421 1034; 177776 277 \621 f 27? <CR> 
*,'182777 

Note that the modified low-order byte 377 must be combined with the 
unmodified high-order byte. 



8.3.13 Relocation Register Commands, r;nR, ;nR, ;R 

The use of the relocation registers is defined in Section 8.2. At the 
beginning of a debugging session it is desirable to preset the 
registers to the relocation biases of those relocatable modules which 
will be receiving the most attention. 

This can be done by typing the relocation bias, followed by a 
semicolon and the specification of relocation registers, as follows: 
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r;nR 



r may be any relocatable expression and n is an integer from to 
If n is omitted it is assumed to be 0. As an example: 

*1000; 5R (puts 1000 into relocation register 5) 
*5. 100; 5R (effectively adds 100 to the contents 
* of relocation register 5) 

Once a relocation register is defined, it can be used to reference 
relocatable values. For example: 

i2300j 1R (puts 2000 into relocation register 1) 
•*i J 5176/ 592466 (examines contents of location 4176) 
*i, 3712; SB " (sets a breakpoint at location 5712) 



In certain uses, programs may be relocated to an address below that at 
which they were assembled. This could occur with PIC code (Position 
Independent Code) which is moved without the use of the Linker. In 
this case the appropriate relocation bias would be the two's 
complement of the actual downward displacement. One method for easily 
evaluating the bias and putting it in the relocation register is 
illustrated in the following example. 

Assume a program was assembled at location 5000 and was moved to 
location 1000. Then the sequence: 

♦1000) 1R 

*1, -5006; 1R 

* 

enters the two's complement of 4000 in relocation register 1, as 
desired. 

Relocation registers are initialized to -1, so that unwanted 
relocation registers never enter into the selection process when ODT 
searches for the most appropriate register. 

To set a relocation register to -1, type ;nR. To set all relocation 
registers to -1, type ;R. 

ODT maintains a table of relocation registers , beginning at the 
address specified by $R. Opening $R ($R/) opens relocation register 0. 
Successively typing a line feed opens the other relocation registers 
in sequence. When a relocation register is opened in this way, it may 
be modified like any other memory location. 



8.3.14 The Relocation Calculators, nR and n! 

When a location has been opened, it is often desirable to relate the 
relocated address and the contents of the location back to their 
relocatable values. To calculate the relocatable address of the 
opened location relative to a particular relocation bias, type n!, 
where n specifies the relocation register. This calculator works with 
opened bytes and words. If n is omitted, the relocation register 
whose contents are closest but less than or equal to the opened 
location is selected automatically by ODT. In the following example, 
assume that these conditions are fulfilled by relocation register 2, 
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which contains 2000. To find the most likely module that a given 
opened byte is in: 

*2588S 611 = 1 =2, 686568 

Typing nR after opening a word causes ODT to print the octal number 
which equals the value of the contents of the opened location minus 
the contents of relocation register n. If n is omitted, ODT selects 
the relocation register whose contents are closest but less than or 
equal to the contents of the opened location. For example, assume the 
relocation bias stored in relocation register 1 is 7000; then: 

*1, 508/ 86688B 1R = 1, 171888 

The value 171000 is the content of 1,500, relative to the base 7000. 
An example of the use of both relocation calculators follows. 

If relocation register 1 contains 1000, and relocation register 2 
contains 2000, then to calculate the relocatable addresses of location 
3000 and its contents, relative to 1000 and 2000, the following can be 
performed. 

*308fV8ti0410 11=1,862868 2 1=2, 881880 1R=1, 177416 2R=2, 176416 



8.3.15 ODT Priority Level, $P 

$P represents a location in ODT that contains the interrupt (or 
processor) priority level at which ODT operates. If $P contains the 
value 377, ODT operates at the priority level of the processor at the 
time ODT is entered. Otherwise $P may contain a value between and 7 
corresponding to the fixed priority at which ODT operates. 

To set ODT to the desired priority level, open $P. ODT prints the 
present contents, which may then be changed: 

*$P/ 686086 377 <CR> 
* 

If $P is not specified, its value is seven. 

ODT priority must be set to if ODT is being used in an F/B 
environment with another job running. 

Breakpoints may be set in routines which run at different priority 
levels. For example, a program running at a low priority may use a 
device service routine which operates at a higher priority level. If 
a breakpoint occurs from a low-priority routine, ODT operates at a low 
priority; if an interrupt occurs from a high priority routine, the 
breakpoints in the high priority routine will not be recognized since 
they were removed when the low priority breakpoint occurred. That is, 
interrupts set at a priority higher than the one at which ODT is 
running will occur and any breakpoints will not be recognized. ODT 
disables all breakpoints from the program whenever it gains control. 
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Breakpoints are enabled when ;P and ;G commands are executed. For 
example : 

*>F/ 08B8B7 5 

+1000; B 

*2000; B 

*1000; G 

BO; 801B88 

* (an interrupt occurs and is serviced) 

If a higher level interrupt occurs while ODT is waiting for input the 
interrupt will be serviced, and no breakpoints will be recognized. 

8.3.16 ASCII Input and Output, r;nA 

ASCII text may be inspected and changed by the command: 

r;nA 

where r is a relocatable expression, and n is a character count. If n 
is omitted it is assumed to be 1. ODT prints n characters starting at 
location r, followed by a carriage return/line feed. Type one of the 
following: 

<CR> ODT outputs a carriage return/line feed and 

an asterisk and waits for another command. 

<LF> ODT opens the byte following the last byte 

output. 

Up to n characters of text 

ODT inserts the text into memory, starting at 
location r. If fewer than n characters are 
typed, terminate the command by typing 
CTRL U, causing a carriage return/line 
feed/asterisk to be output. However, if 
exactly n characters are typed, ODT responds 
with a carriage return/line feed, the address 
of the next available byte and a carriage 
return/line feed/asterisk. 

ODT does not check the magnitude of n. 

8.4 PROGRAMMING CONSIDERATIONS 

Information in this section is not necessary for the efficient use of 
ODT. However, it does provide a better understanding of how ODT 
performs some of its functions and in certain difficult debugging 
situations, this understanding is necessary. 

8.4.1 Functional Organization 

The internal organization of ODT is almost totally modularized into 
independent subroutines. The internal structure consists of three 
major functions: command decoding, command execution, and various 
utility routines. 

The command decoder interprets the individual commands, checks ior 
command errors, saves input parameters for use in command execution, 
and sends control to the appropriate command execution routine. 
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The command execution routines take parameters saved by the command 
decoder and use the utility routines to execute the specified command. 
Command execution routines exit either to the object program or back 
to the command decoder. 

The utility routines are common routines such as SAVE-RESTORE and I/O. 
They are used by both the command decoder and the command executers. 

8.4.2 Breakpoints 

The function of a breakpoint is to give control to ODT whenever the 
user program tries to execute the instruction at the selected address 
Upon encountering a breakpoint, all of the ODT commands can be used to 
examine and modify the program. 

When a breakpoint is executed, ODT removes all the breakpoint 
instructions from the user's code so that the locations may be 
examined and/or altered. ODT then types a message on the terminal of 
the form Bn;k where k is the breakpoint address (and n is the 
breakpoint number). The breakpoints are automatically restored when 
execution is resumed. 

A major restriction in the use of breakpoints is that the word where a 
breakpoint was set must not be referenced by the program in any way 
since ODT altered the word. Also, no breakpoint should be set at the 
location of any instruction that clears the T-bit. For example: 

MOV #240,177776 ;SET PRIORITY TO LEVEL 5 

NOTE 

Instructions that cause or return from 
traps (e.g., EMT, RTI) are likely to 
clear the T-bit, since a new word from 
the trap vector or the stack is loaded 
into the Status Register. 

A breakpoint occurs when a trace trap instruction (placed in the user 
program by ODT) is executed. When a breakpoint occurs, the following 
steps are taken: 

1. Set processor priority to seven (automatically set by trap 
instruction) . 

2. Save registers and set up stack. 

3. If internal T-bit trap flag is set, go to step 13. 

4. Remove breakpoints. 

5. Reset processor priority to ODT's priority or user's 
priority. 

6. Make sure a breakpoint or single-instruction mode caused the 
interrupt. 

7. If the breakpoint did not cause the interrupt, go to step 15. 

8. Decrement repeat count. 

9. Go to step 18 if non-zero; otherwise reset count to one. 

10. Save terminal status. 

11. Type message about the breakpoint or single-instruction mode 
interrupt. 
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12. Go to command decoder. 

13. Clear T-bit in stack and internal T-bit flag. 

14. Jump to the Go processor. 

15. Save terminal status. 

16. Type BE (Bad Entry) followed by the address. 

17. Clear the T-bit, if set, in the user status and proceed to 
the command decoder. 

18. Go to the Proceed processor, bypassing the TT restore 
routine. 

Note that steps 1-5 inclusive take approximately 100 microseconds 
during which time interrupts are not permitted (ODT is running at 
level 7) . 

When a proceed (;P) command is given, the following occurs: 

1. The proceed is checked for legality. 

2. The processor priority is set to seven. 

3. The T-bit flags (internal and user status) are set. 

4. The user registers, status, and Program Counter are restored. 

5. Control is returned to the user. 

6. When the T-bit trap occurs, steps 1, 2, 3, 13, and 14 of the 
breakpoint sequence are executed, breakpoints are restored, 
and program execution resumes normally. 

When a breakpoint is placed on an IOT, EMT, TRAP, or any instruction 
causing a trap, the following occurs: 

1. When the breakpoint occurs as described above, ODT is 
entered . 

2. When ;P is typed, the T-bit is set and the IOT, EMT, TRAP, or 
other trapping instruction is executed. 

3. This causes the current PC and status (with the T-bit 
included) to be pushed on the stack. 

4. The new PC and status (no T-bit set) are obtained from the 
respective trap vector. 

5. The whole trap service routine is executed wiithout any 
breakpoints . 

6. When an RTI is executed, the saved PC and PS (including the 
T-bit) are restored. The instruction following the 
trap-causing instruction is executed. If this instruction is 
not another trap-causing instruction, the T-bit trap occurs, 
causing the breakpoints to be reinserted in the user program, 
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or the single-instruction mode repeat count to be 
decremented. If the following instruction is a trap-causing 
instruction, this sequence is repeated starting at step 3. 

NOTE 

Exit from the trap handler must be via 
the RTI instruction. Otherwise, the 
T-bit is lost. ODT can not regain 
control since the breakpoints have not 
been reinserted yet. 

Note that the ;P command is illegal if a breakpoint has not occurred 
(ODT responds with ?) ; ;P is legal, however, after any trace trap 
entry. v 

The internal breakpoint status words have the following format: 

1. The first eight words contain the breakpoint addresses for 
breakpoints 0-7. (The ninth word contains the address of the 
next instruction to be executed in single-instruction mode.) 

2. The next eight words contain the respective repeat counts. 
The following word contains the repeat count for 
single-instruction mode.) 

These words may be changed at will, either by using the breakpoint 
commands or by direct manipulation with $B. 

When program runaway occurs (that is, when the program is no longer 
under ODT control, perhaps executing an unexpected part of the proqram 
where a breakpoint has not been placed) , ODT may be given control by 
pressing the HALT key to stop the computer, and restarting ODT (see 
Section 8.1). ODT prints *, indicating that it is ready to accept a 
command . 



or 



If the program being debugged uses the teleprinter for input Wi 
output, the program may interact with ODT to cause an error since ODT 
uses the teleprinter as well. This interactive error will not occur 
when the program being debugged is run without ODT. 

Note the following rules concerning the ODT break routine: 

1# K f fc v e tel< fP rinter interrupt is enabled upon entry to the ODT 
break routine, and no output interrupt is pending when ODT is 
entered, ODT generates an unexpected interrupt when returning 
control to the program. 

2. If the interrupt of the teleprinter reader (the keyboard) is 
enabled upon entry to the ODT break routine, and the program 
is expecting to receive an interrupt to input a character, 
both the expected interrupt and the character are lost. 

3. If the teleprinter reader (keyboard) has just read a 
character into the reader data buffer when the ODT break 
routine is entered, the expected character in the reader data 
buffer is lost. 
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8.4.3 Searches 



The word search allows the user to search for bit patterns in 
specified sections of memory. Using the $M/ command, the user 
specifies a mask, a lower search limit ($M+2), and an upper search 
limit ($M+4). The search object is specified in the search command 
itself. 

The word search compares selected bits (where ones appear in the mask) 
in the word and search object. If all of the selected bits are equal, 
the unmasked word is printed. 

The search algorithm is : 

1. Fetch a word at the current address. 

2. XOR (exclusive OR) the word and search object. 

3. AND the result of step 2 with the mask. 

4. If the result of step 3 is zero, type the address of the 
unmasked word and its contents. Otherwise, proceed to step 
5. 

5. Add two to the current address. If the current address is 
greater than the upper limit, type * and return to the 
command decoder, otherwise go to step 1. 

Note that if the mask is zero, ODT . prints every word between the 
limits, since a match occurs every time (i.e., the result of step 3 is 
always zero). 

In the effective address search, ODT interprets every word in the 
search range as an instruction which is interrogated for a possible 
direct relationship to the search object. The mask register is opened 
only to gain access to the search limit registers. 

The algorithm for the effective address search is (where (X) denotes 
contents of X, and K denotes the search object) : 

1. Fetch a word at the current address X. 

2. If (X)=K [direct reference], print contents and go to step 5. 

3. If (X)+X+2=K [indexed by PC], print contents and go to step 
5. 

4. If (X) is a relative branch to K, print contents. 

5. Add two to the current address. If the current address is 
greater than the upper limit, perform a carriage return/line 
feed and return to the command decoder; otherwise, go to 
step 1. 



8.4.4 Terminal Interrupt 

Upon entering the TT SAVE routine, the following occurs 
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1. Save the LSR status register (TKS) . 

2. Clear interrupt enable and maintenance bits in the TKS, 

3. Save the TT status register (TPS) . 

4. Clear interrupt enable and maintenance bits in the TPS. 
To restore the TT: 

1. Wait for completion of any I/O from ODT. 

2. Restore the TKS. 

3. Restore the TPS. 



NOTES 

If the TT printer interrupt is enabled 
upon entry to the ODT break routine, the 
following may occurs 

1. If no output interrupt is 
pending when ODT is entered, an 
additional interrupt always 
occurs when ODT returns control 
to the user. 

2. If an output interrupt is 
pending upon entry, the 
expected interrupt occurs when 
the user regains control. 

If the TT reader (keyboard) is busy or 
done, the expected character in the 
reader data buffer is lost. 

If the TT reader (keyboard) interrupt is 
enabled upon entry to the ODT break 
routine, and a character is pending, the 
interrupt (as well as the character) is 
lost. 



8.5 ODT ERROR DETECTION 

ODT detects two types of error: illegal or unrecognizable command and 
bad breakpoint entry. ODT does not check for the legality of an 
address when commanded to open a location for examination or 
modification. Thus the command: 

*17???4/ 

7M-TRRP TO 4 003362 



references nonexistent memory, thereby causing a trap through the 
vector at location 4. If this vector has not been properly 
initialized, unpredictable results occur. 
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Typing something other than a legal command causes ODT to ignore the 
command, print: 

(echoes illegal command)? 
* 

and wait for another command. Therefore, to cause ODT to ignore a 
command just typed, type any illegal character (such as 9 or RUBOUT) 
and the command will be treated as an error, i.e., ignored. 

ODT suspends program execution whenever it encounters a breakpoint, 
i.e., traps to its breakpoint routine. If the breakpoint routine is 
entered and no known breakpoint caused the entry, ODT prints: 

BEnnnnnn 

and waits for another command. BEnnnnnn denotes Bad Entry from 
location nnnnnn. A bad entry may be caused by an illegal trace trap 
instruction, setting the T-bit in the status register, or by a jump to 
the middle of ODT. 



8-26 



CHAPTER 9 
PROGRAMMED REQUESTS 



A number of services at the machine language level which the monitor 
regularly provides to system programs are also available to 
user-written programs. These include services for file manipulation, 
command interpretation, and facilities for input and output 
operations. User programs call these monitor services by means of 
"programmed requests", which are assembler macro calls written into 
the user program and interpreted by the monitor at program execution 
time. 



NOTE 

Programmed requests used in Version 2 
differ from those used in Version 1; for 
example, the channel number in Version 1 
was limited to the range 0-17, where it 
is not in Version 2; blank fields in 
macro calls were not allowed in Version 
1, and are in Version 2% a .area 
argument points to an argument list in 
Version 2, where arguments were pushed 
on the stack in Version 1. 

Programs written for use under Version 1 
will assemble and execute properly when 
the ..VI.. macro call (explained in 
Section 9.3.1.5) is included, but it is 
to the user's advantage to convert these 
programs so they use the new Version 2 
macro calls wherever possible. Only 
macro calls which are used with the 
current version of RT-11 (Version 2) are 
discussed in this chapter. See Section 
9 . 5 for instructions on converting 
Version 1 macro calls to the Version 2 
format . 



The macro definitions for both Version 1 and Version 2 requests are 
included in the file SYSMAC.SML (in 8K systems, the system macro 
library is called SYSMAC.8K); Appendix D provides a listing of 
SYSMAC.SML. Refer to Chapter 5 for general information related to the 
use of macro calls. 

The FORTRAN programmer should note that the system subroutine library 
(SYSLIB) gives him the same capability (under FORTRAN) to use the 
programmed requests which are available to the machine language 
programmer and described in this chapter. SYSLIB users should first 
read this chapter and then read Appendix O. 

9-1 



Programmed Requests 

9.1 FORMAT OF A PROGRAMMED REQUEST 

The basis of a programmed request is the EMT instruction, used to 
communicate information to the monitor. When an EMT is executed, 
control is passed to the monitor, which extracts appropriate 
information from the EMT and executes the function required. The 
low-order byte of the EMT instruction contains a code which is 
interpreted as: 

Low-Order Byte 

of EMT Meaning 

377 Reserved; RT-11 ignores this EMT and returns 
control to the user program immediately. 

376 Used internally by the RT-11 monitor; this EMT 
code should never be used by user programs. 

375 Programmed request with several arguments: RO 
must point to a list of arguments which designates 
the specific function. 

374 Programmed request with one argument: RO contains 
a function code in the high-order byte and a 
channel number (see Section 9.2.1) or in the 
low-order byte. 

360-373 Used internally by the RT-11 monitor; these EMT 
codes should never be used by user programs. 

340-357 Programmed request with arguments on the stack 
and/or in RO. 

0-337 Version 1 programmed request. These EMTs use 

arguments both on the stack and in RO. They are 

supported for binary compatability with Version 1 
programs . 

A programmed request consists of a macro call followed, where 
necessary, by one or more arguments. Arguments supplied to a macro 
call must be legal assembler expressions since arguments will be used 
as source fields in MOV instructions when the macros are expanded at 
assembly time. The following two formats are used: 

1. PRGREQ ARG1,ARG2,...ARGN 

2. PRGREQ AREA,ARG1,ARG2,...ARGN 

Form 1 above contains the arguments ARG1 through ARGN; no argument 
list pointer is required. Macros of this form generate either an EMT 

374 or one of the EMTs 340-357. Certain arguments for this form may be 
omitted; refer to the listing of SYSMAC.SML in Appendix D. 

In form 2 above, AREA is a pointer to the argument list which contains 
the arguments ARGl through ARGN. This form always causes an EMT 375 
to be generated. Blank fields are permitted; however, if the AREA 
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argument is blank, the macro assumes that RO points to a valid I 
argument block (see Section 9.2.3). If any of the fields ARG1 to ARGN 
are blank, the corresponding entries in the argument list are left 

untouched. Thus, 

.PRGREQ AREA,A1,A2 

points RO to the argument block at AREA and fills in the first and 
second arguments, while: 

.PRGREQ AREA 

points RO to the block, and fills in the first word but does not fill 

in any other arguments . 

The call: 

.PRGREQ ,A1 

assumes RO points to the argument block and fills in the Al argument, 
but leaves the A2 argument alone. The call: 

. PRGREQ 

generates only an EMT 375 and assumes that both RO and the block to 
which it points are properly set up. 

The arguments to RT-11 programmed request macros all serve as the 
source field of a MOV instruction which moves a value into the 
argument block or RO. For example: 

.PRGREQ CHAR 

expands into: 

MOV CHAR,R0 
EMT 357 

Care should be taken to make certain that the arguments specified are 
legal source fields and that the address accurately represents the 
value desired. If the value is a constant, immediate mode [#] should 
be used; if the value is in a register, the register mnemonic [Rn] 
should be used; if the value is indirectly addressed, the appropriate 
register convention is necessary [@Rn] , and if the value is in memory, 
the label of the location whose value is the argument is used. 

Following are some examples of both correct and incorrect macro calls. 
Consider the general request: 

. PRGREQ . AREA , . ARG1 , . . . ARGN 
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A more common way of writing a request of this form is: 

. PRGREQ # ARE A , # ARG1 , . . . # ARGN 

In this format, the address of AREA is put directly into the argument 
list. AREA is the tag which indicates the beginning of the argument 
block. For example: 

.PRGREQ # ARE A, #4 



AREA: .BLKW 3 

When a direct numerical argument is required, the # causes the correct 
value to be put into the argument block. For example: 

.PRGREQ # AREA, #4 

is correct, while: 

.PRGREQ # AREA, 4 

is not. This form interprets the 4 as meaning "move the contents of 
location 4 into the argument block", where the number 4 itself should 
be moved into the block. 

If the request is written ass 

.PRGREQ AREA, #4 

it is interpreted as "use the contents of location AREA as the list 
pointer", when the address of AREA is actually desired. This 
expansion could be used with the following form: 

.PRGREQ LIST1,#4 



LIST1 : AREA 
AREA: .BLKW3 

In this case, the content of location LIST1 is the address of the 
argument list. Similarly, this form is correct: 

.PRGREQ LIST1, NUMBER 
LIST1 : AREA 
NUMBER: 4 

In thi3 case, the contents of the locations T.-IST1 and NUMBER are the 
argument list pointer and data value.- respectively. 

NOTE 

All registers except RO are preserved 
across a programmed request. (In 
certain cases, RO may contain 
information passed back by the monitor; 
however, unless the description of a 
request indicates that a specific value 
is returned in RO, it may be assumed 
that the contents of RO are 
unpredictable upon return from the 
request) . With the exception of calls to 
the CSI, the position of the stack 
pointer is also preserved across a 
programmed request. 
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9.2 SYSTEM CONCEPTS 



Some basic operational characteristics and concepts of RT-11 are 
described below. 



9.2.1 Channel Number (chan) 

A channel number is a logical identifier in the range to 377 (octal) 
for a file or "set of data" used by the RT-11 monitor. Thus, when a 
file is opened on a particular device, a channel number is assigned to 
that file. To refer to an open file, it is only necessary to refer to 
the appropriate channel number for that file. 



9.2.2 Device block (dblk) 

A device block is a four-word block of radix-50 information which 
specifies a physical device and file name for an RT-11 programmed 
request, (Refer to Chapter 5 for an explanation of .RAD50 strings.) 
For example, a device block representing a file FILE. EXT on device DK: 
could be written as: 

.RAD50 /DK / 

.RAD50 /FIL/ 

.RAD50 /E / 

. RAD50 /EXT/ 

The first word contains the device name, the second and third words 
contain the file name, and the fourth contains the extension. Device, 
name, and extension must each be left- justified in the appropriate 
field. This string could also be written as: 

.RAD50 /DK FILE EXT/ 

Note that spaces must be used to fill out each field. Note also that 
the colon and period separators do not appear in the actual RAD50 
string. They are used only by the monitor keyboard interface to 
delimit the various fields. 

9.2.3 EMT Argument Blocks 

Programmed requests which call the monitor via EMT 375 use RO as a 
pointer to an argument list. In general, this argument list appears 
as follows : 



address 


contents 




Function Channel 


X 


Code Number 


x+2 


argument 1 


x+4 


argument2 
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RO points to location x. The even (low-order) byte of location x 
contains the channel number named in the macro call. If no channel 
number is required, the byte is set to 0. The odd (high-order) byte of 
x is a code specifying the function to be performed. Locations x+2, 
x+4, etc. contain arguments to be interpreted. These are described 
in detail under each request. 

Requests which use EMT 374 set up RO with the channel number in the 
even byte and the function code in the odd byte. They require no 
other arguments. 



9.2.4 Important Memory Areas 



9.2.4.1 Vector Addresses (0-37, 60-477) - Certain areas of memory 
between and 477 are reserved for use by RT-11. KMON does not load 
these locations from the save image file when it initiates a program,, 
i.e., R, RUN, and GET will not load these words. However, no hardware 
memory protection is supplied. Thus, programs should never alter the 
contents of the indicated areas at run-time. 

Locations Contents 

Monitor restart. Executes .EXIT request and 
returns control to KMON. 

Time out or bus error trap; RT-11 sets this to 
point to its internal trap handler. 

Reserved instruction trap; RT-11 sets this to 
point to its internal trap handler. 

EMT trap vector and status. 

RT-11 system communication area (see below) . 

TTY input interrupt vector and status. 

TTY output interrupt vector and status. 

100,102 KW11L vector and status. 

204,206 RF11 vector and status. 

214,216 TC11 vector and status. 

220,222 RK05 vector and status. 

330,332 GT40 shift out interrupt vector and status. 

These areas are not replaced by RT-11. If they are destroyed by a 
program, the system must be re-bootstrapped, or the program must 
restore them. 



0,2 




4,6 




10, 


12 


30, 


32 


40- 


57 


60, 


62 


64, 


66 
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9.2.4.2 Resident Monitor - Section 2.4 of Chapter 2 describes the 
placement of monitor components when either the Single- Job Monitor or 
F/B Monitor is brought into memory; included is the approximate size 
of each monitor component and the size of the area available for 
handlers and user programs. 



9.2.4.3 System Communication Area - RT-11 uses bytes 40-57 to hold 
information about the program currently executing, as well as certain 
information used only by the monitor. A description of these bytes 
follows t 

Bytes Meaning and Use 

40,41 Start address of job. When a file is linked into 
an RT-11 memory image, this word is set to the 
starting address of the job either with the Linker 
/T switch or as an argument in the .END statement 
of the program. When a foreground program is 
executed, the PRUN processor relocates this word 
to contain the actual starting address of the 
program. 

42,43 Initial value of the stack pointer. If it is not 
set by the user program in an .ASECT, it defaults 
to 1000 or the top of the .ASECT in the 
background, whichever is larger. If a foreground 
program does not specify a stack pointer in this 
word, a default stack (128 decimal words) is 
allocated by FRUN immediately below the program. 
The initial stack pointer can also be set with the 
Linker /M switch option. 

44,45 Job Status Word. Used as a flag word for the 
monitor. Certain bits are maintained by the 
monitor exclusively while others must be set or 
cleared by the user job. Those bits in the 
following list which are marked by an asterisk are 
bits which must be set by the user job. 

Since the currently unassigned bits may be used in 
future releases of RT-11, user programs should not 
use these bits for internal flags. 

Bit 

Number Meaning 

15 USR swap bit. (Unused in F/B.) The 

monitor sets this bit when programs do 

not require the USR to be swapped. see 

Section 9.2.5 for details on USR 
swapping. 

14 Lower-case bit. When set (automatically 
by EDIT when the EL command is typed) , 
disables conversion of lower-case to 
upper-case. 

*13 Reenter bit. When set, this bit 
indicates that the program may be 
restarted from the terminal with the 
REENTER command. 
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*12 Special mode TT bit. When set, this bit 
indicates that the job is in a "special" 
keyboard mode of input. Refer to the 
explanation of the .TTYIN/.TTINR 
requests for details. 

11-10 For F/B Monitor use only. 

9 Overlay Bit. Set (by the Linker) if the 
job uses the Linker overlay structure. 

8 CHAIN bit. If this bit is set in a 
job's save image, words 500-776 are 
loaded from the save file when the job 
is started even if the job is entered 
via CHAIN. (These words are normally 
used to pass parameters across CHAINS.) 
The bit is set when a job is running if 
and only if the job was actually entered 
with CHAIN. 

*7 Error halt bit. When set, this bit 
indicates a halt on an I/O error. If 
the user desires to halt when any I/O 
device error occurs, this bit should be 
set. (Unused in F/B.) 

*6 Inhibit TT wait bit. For use with the 
Foreground/Background system. When set, 
this bit inhibits the monitor from 
entering a console terminal wait state. 
Refer to the sections concerning 
.TTYIN/.TTINR, and .TTYOUT/.TTOUTR for 
more information. 

5-0 Unused. 

46,47 USR load address. Normally 0, this word may be 
set to any valid word address in the user's 
program. See Section 9.2.5, Swapping Algorithm, 
for details of use. 

50,51 High memory address. The monitor maintains the 
highest address the user program can use in this 
word. The Linker sets it initially. It is 
modified only via the .SETTOP (Set Top of Memory) 
monitor request. 

52 EMT error code. If a monitor request results in 
an error, the code number of the error is always 
returned in byte 52 and the carry bit is set. Each 
monitor call has its own set of possible errors. 
It is recommended that the user program reference 
byte 52 with absolute addressing, rather than 
relative addressing. For example: 

ERRWRD =52 

TSTB ERRWRD ; RELATIVE ADDRESSING 

TSTB <3#ERRWRD ; ABSOLUTE ADDRESSING 
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NOTE 



Location 52 must always be addressed as 
a byte, never as a word, since byte 53 
will be used in future releases of 
RT-11. 

53 Reserved for future system use. 

54,55 Address of the beginning of the Resident Monitor. 
RT-11 always loads the resident into the highest 
available memory locations; this word points to 
its first location. It must never be altered by 
the user. Doing so will cause RT-11 to 
malfunction. 



56 



57 



Fill character (7-bit ASCII). Some high-speed 
terminals require filler (null) characters after 
printing certain characters. Byte 56 should 
contain the ASCII 7-bit representation of the 
character after which fillers are required. 

Fill count. This byte specifies the number of 
fill characters required. If bytes 56 and 57=0, 
no fillers are required. 

The required fill characters are: 









Value of 


Terminal 




No. of fills 


Word 56 


Serial LA30 @ 300 


baud 


10 after carriage return 


5015 


Serial LA30 @ 150 


baud 


4 after carriage return 


2015 


Serial LA30 @ 110 


baud 


2 after carriage return 


1015 


VT05 @ 2400 


baud 


4 after line feed 


2012 


VT05 @ 1200 


baud 


2 after line feed 


1012 


VT05 @ 600 


baud 


1 after line feed 


412 



9.2.5 Swapping Algorithm 

Programmed requests are divided into two categories according to 
whether or not they require the USR to be in memory (see Table 9-2). 
Any request which requires the USR in memory may also require that a 
portion of the user program be saved temporarily on the system device 
scratch blocks (i.e., be "swapped out") to provide room for the USR. 
The USR will be read into the swapped region. 

During most normal operations, this swapping is invisible to the user 
and he need not be concerned about it. However, it is possible to 
optimize programs so that they require little or no swapping. This is 
particularly useful when operating in an F/B environment, since under 
the F/B system, the USR will be swapped for both background and 
foreground jobs regardless of which job required it. If the USR is 
not swapped, neither the foreground nor the background job will be 
slowed down by the swapping process. 

The following items should be considered if a swap operation is 
necessary: 

1. The background job - If a .SETTOP request in a background job 
specifies an address beyond the point at which the USR 
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2. 



normally resides, a swap will be required when the USR is 
called. More details concerning the .SETTOP request are in 
Section 9.4.36. 

The value of location 46 - If the user either assembles an 
address into word 46 or moves a value there while the program 
is running, RT-11 uses the contents of that word as an 
alternate place to swap the USR. If location 46 is 0, this 
indicates that the USR will be at its normal location in high 
memory. 

NOTES 

1. If the USR does not require 
swapping, the value in location 46 
is ignored. Swapping is a 
relatively time-consuming operation 
and is avoided, if possible. 

2. A foregroxmd job should always have 
a value in location 46 unless it is 
certain that the USR will never be 
swapped. If the foreground job does 
not allow space for the USR and a 
swap is required, a fatal error 
occurs. (The SET USR NOSWAP 
command, explained in Chapter 2, 
ensures that the USR will be 
resident.) 

3. Care should be taken when specifying 
an alternate address to location 46. 
The single-job system does not 
verify the legality of the USR swap 
address. Thus, if the area to be 
swapped overlays the Resident 
Monitor, the system is destroyed. 

4. The user should also take care that 
the USR is never swapped over any of 
the following areas: the program 
stack; any parameter block for 
calls to the USR; any I/O buffers, 
device handlers, or completion 
routines being used when the USR is 
called. 



The following is an example of the way a background program can avoid 
unnecessary USR swapping. 

.MCALL ,.V«>.,,.»EPDFF,.SfcTTOP f .FXTT 

.WtGDEF 
RM PTR,«;a JPOJNTFH TO RMON IS AT S«, 

USRL0C«2«>b (POINTER TO USR LOCATION IS 

fAT ?6* BYTES INTO RMON. 
START: 

MOV »#PMPTP.R1 »hi -> RESIDENT MONITOR 

MOV USRLOC(Ri) ,R0 *R0 "> 'JSP 

TST -C»tf) fPQINT JUST BELQW 
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!$: 



CMP R0,»#5B 

PHI 1$ 

MOV #«?,R0 

•StTTOP 

MOV R0.HILIM 



.EXJT 
HILIMi ,«UHO pi 

•END ST4RT 



;dpes usr swap over us? 

IMO, QK 

JYFS, USR MUST SWAP 

»ASK FOR MFMORY UP TCI USR 

JR0I « HJGH LTMTT OF MEMORY 

MCTUALLY GRANTED RY MONITOR. 

JCnwTAlNS HI LTMTT OF MEMORY 



9.2.6 Offset Words 

There are several words which always have fixed positions relative to 
the start of the Resident Monitor. It is often advantageous for user 
programs to be able to access these words. This is done with the 
code: 



RMON = 54 

MOV @#RMON, register 

MOV OFFSET (register) , register 

Here, register is any general register and OFFSET is a number from the 
following list: 

OFFSET (Bytes) Contents 

262 System date. (See .DATE request.) 



266 



270 



275 
276 

277 



300 



Start of normal USR area. This is where the 
USR will reside when it is non-swapping. It 
is useful to be able to perform a .SETTOP in 
a background job such that the USR is always 
resident. (An example is in Section 9.2.5.) 

Address of I/O exit routine for all devices. 
The exit routine is an internal queue 
management routine through which all device 
handlers exit once the I/O transfer is 
complete. Any new devices added to RT-11 
must also use this exit location. 

Unit number of system device (device from 
which system was last bootstrapped) . 

Monitor version number (2-377) . The user can 
always access the version number to determine 
if the most recent monitor is in use. 

Update number. Patches to the monitor always 
increment the update number. This provides a 
means of checking that all patches have been 
made. (This number should be accessed by 
MOVE rather than MOV) . 

Configuration word. This is a string of 16 
bits used to indicate information about 
either the hardware configuration of the 
system, or a software condition. The bits 
and their meanings are: 
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Bit # Meaning 

= Single- Job Monitor 
1 = F/B Monitor 

2 1 ■ GT40 display hardware exists 

3 1 - RT-11 BATCH is in control 

of the background 

5 = 60-cycle clock 
1 = 50-cycle clock 

6 1 - 11/45 floating-point 

hardware exists 

7 = No foreground job is in memory 
1 = Foreground job is in memory 

8 1 - User is linked to the GT40 

scroller 

9 1 - USR is permanently resident 

(via a SET USR NOSWAP) 
11 1 = Processor is an 11/03 

15 1 = KW11L clock is present 

(always set if 11/03) 



304-313 



The other bits are reserved for future use 
and should not be accessed by user programs. 

These locations contain the addresses of the 
console terminal control and status 
registers. The order is: 



304 Keyboard status 

306 Keyboard buffer 

310 Printer status 

312 Printer buffer 



314 



324 



354 



These locations can be changed, for example, 
to reflect a second terminal; thus RT-11 can 
be made to run on any terminal present on the 
system which is connected to the machine via 
the DL11 multiple terminal interface. (Refer 
to the RT-11 Software Support Manual 
(DEC-11-0RPGA-B-D) . 

The maximum file size allowed in a length 
.ENTER. This can be adjusted by the user 
program or by using the PATCH program to be 
any reasonable value. The default value is 
177777 (decimal) blocks, allowing an 
essentially unlimited file size. 

Address of .SYNCH entry. User interrupt 
routines may enter the monitor through this 
address to synchronize with the job they are 
servicing. 

Address of VT11 display processor display 
stop interrupt vector. 
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9.2.7 File Structure 

RT-11 uses a "contiguous" file structure. This type of structure 
implies that every file on the device is made up of a contiguous group 
of physical blocks. Thus, a file that is 9 blocks long occupies 9 
contiguous blocks on the device. 

A contiguous area on a device can be in one of the following 
categories : 

1. Permanent file. This is a file which has been .CLOSEd on a 
device. Any named files which appear in a PIP directory 
listing are permanent files. 

2. Tentative file. Any file which has been created via .ENTER, 
but not .CLOSEd, is a tentative file entry. When the .CLOSE 
request is given, the tentative entry becomes a permanent 
file. If a permanent file already exists under the same 
name, the old file is deleted. If a .CLOSE is never given, 
the tentative file is treated like an empty entry. 

3. Empty entry. When disk space is unused or a permanent file 
is deleted, an empty entry is created. Empty entries appear 
in a PIP /E directory listing as <UNUSED> N, where N is the 

decimal block length of the empty area. 

Since a contiguous structure does not automatically reclaim unused 
disk space, the device may eventually become "fragmented". A device is 
fragmented when there are many empty entries which are scattered over 
the device. RT-11 PIP has an option which allows the user to collect 
all empty areas so that they occur at the end of a device. Refer to 
Chapter 4 for details. 



9.2.8 Completion Routines 

Completion routines are user-written routines which are entered 
following an operation. On entry to a completion routine, RO contains 
the channel status word for the operation; Rl contains the octal 
channel number of the operation. The carry bit is not significant. 

Completion routines are handled differently in the Single-Job and the 
P/B versions of RT-11. In the Single- Job version, completion routines 
are totally asynchronous and can interrupt one another. In F/B, 
completion routines do not interrupt each other. Instead they are 
queued and made to wait until the correct job is running. For 
example, if a foreground job is running and an I/O transfer initiated 
by a background job completes and wants to go to a completion routine, 
the background routine is queued and will not execute until the 
foreground gives up control of the system. If the foreground is 
running and a foreground I/O transfer completes and wants a completion 
routine, that routine will be entered immediately if the foreground is 
not already inside a completion routine. If it is in a completion 
routine, that routine continues to termination, at which point any 
other completion routines are entered in a first in/first out manner. 
If the background is running and a foreground I/O transfer completes 
and needs a completion routine, the background is suspended and the 
foreground routine is entered immediately. 
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The restrictions which must be observed when writing completion 
routines are: 

1. Completion functions cannot issue a request which would cause 
the USR to be swapped in. They are primarily used for 
issuing READ/WRITE commands, not for opening or closing 
files, etc. A fatal monitor error is generated if the USR is 
called from a completion routine. 

2. Completion routines should never reside in the memory space 
which will be used for the USR, since the USR can be 
interrupted when I/O terminates and the completion routine is 
entered. If the USR has overlaid the routine, control 
passes to a random place in the USR, with a HALT or error 
trap the likely result. 

3. The routine must be exited via an RTS PC, as it is called 
from the monitor via a JSR PC,ADDR where ADDR is the 
user-supplied address. 

4. If a completion routine uses registers other than RO or Rl, 
it must save them upon entry and restore them before exiting. 



9.2.9 Using the System Macro Library 

User programs for RT-11 should always be written using the system, 
macro library (SYSMAC.SML) , supplied with RT-11. This ensures 
compatibility among all user programs and allows easy modification by 
redefining a macro. A listing of SYSMAC.SML appears in Appendix D. 

The system macro library for 8K systems appears on the system device 
as SYSMAC.8K. 

Suggestions for writing foreground programs are in Appendix H, F/B 
Programming and Device Handlers. This appendix should be read in 
conjunction with Chapter 9 before coding F/B programs. 



9.3 TYPES OF PROGRAMMED REQUESTS 

There are three types of services which the monitor makes available to 
the user through programmed requests. These are: 

1. Requests for File Manipulation 

2. Requests for Data Transfer 

3. Requests for Miscellaneous Services 

Table 9-1 summarizes the programmed requests in each of theses 

categories alphabetically. Those marked with an asterisk function 

only in a F/B environment; they are ignored under the Single- Job 

Monitor. The EMT and function code for each request (where 
applicable) are included. 
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Table 9-1 
Summary of Programmed Requests 



Mnemonic 


EMT & 
Code 


Section 


Purpose 


File Manipulation Requests 


*.CHCOPY 

.CLOSE 
.DELETE 

.ENTER 
.LOOKUP 

.RENAME 
. REOPEN 

.SAVE STATUS 


375 

374 
375 

375 
375 

375 
375 

375 


13 

6 


2 

1 

4 
6 

5 


9.4.3 

9.4.4 
9.4.10 

9.4.13 
9.4.21 

9.4.32 
9.3.33 

9.4.34 


Establishes a link and allows one 
job to access another job's 
channel . 

Closes the specified channel. 

Deletes the file from the specified 
device . 

Creates a new file for output. 

Opens an existing file for input 
and/or output via the specified 
channe 1 . 

Changes the name of the indicated 
file to a new name. 

Restores the parameters stored via 
a SAVESTATUS request and reopens 
the channel for I/O. 

Saves the status parameters of an 
open file in user memory and frees 
the channel for future use. 


Data Transfer Requests 


* . RCVD 
* . RCVDW 
* . RCVDC 

.READ 
.RE ADC 


375 
375 

375 


26 

10 

10 


9.4.29 
9.4.30 

9.4.30 


Receives data. Allows a job to 
read messages or data sent by 
another job in an F/B environment. 
The three modes correspond to the 
READ, .READC, and READW modes. 

Transfers data via the specified 
channel to a memory buffer and 
returns control to the user program 
when the transfer request is 
entered in the I/O queue. No 
special action is taken upon 
completion of I/O. 

Transfers data via the specified 
channel to a memory buffer and 
returns control to the user program 
when the transfer request is 
entered in the I/O queue. Upon 
completion of the read, control 
transfers asynchronously to the 
routine specified in the .READC 
request. 
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Summary of Programmed Requests 



Mnemonic 


EMT & 
Code 


Section 


Purpose 


.READW 


375 


10 


9.4.30 


Transfers data via the specified 
channel to a memory buffer and 
returns control to the user program 
only after the transfer is 
complete. 


*.SDAT 
* . SDATC 
* . SDATW 


375 


25 


9.4.35 


Allows the user to send messages or 
data to the other job in an F/B 
environment. The three modes cor- 
respond to the .WRITE, .WRITC and 
.WRITW modes. 


.TTYIN 
.TTINR 


340 


— 


9.4.43 


Transfers one character from the 
keyboard buffer to R0. 


.TTYOUT 
.TTOUTR 


341 


— 


9.4.44 


Transfers one character from R0 
to the terminal input buffer. 


.WRITE 


375 


11 


9.4.47 


Transfers data via the specified 
channel to a device and returns 
control to the user program when 
the transfer request is entered in 
the I/O queue. No special action 
is taken upon completion of the 
I/O. 


.WRITC 


375 


11 


9.4.47 


Transfers data via the specified 
channel to a device and returns 
control to the user program when 
the transfer request is entered in 
the I/O queue. Upon completion of 
the write, control transfers 
asynchronously to the routine 
specified in the .WRITC request. 


.WRITW 


375 


11 


9.4.47 


Transfers data via the specified 
channel to a device and returns 
control to the user program only 
after the transfer is complete. 


Miscellaneous Se 


rvices 






.CDFN 


375 


15 


9.4.1 


Defines additional channels for 
doing I/O. 


.CHAIN 


374 


10 


9.4.2 


Chains to another program (in the 
background job only) . 


*.CMKT 


375 


23 


9.4.5 


Cancels an unexpired mark time 
request. 


*.CNTXSW 


375 


33 


9.4.6 


Requests that the indicated memory 
locations be part of the F/B 
context switch process. 


.CSIGEN 


344 


— 


9.4.7 


Calls the Command String 
Interpreter (CSI) in general mode. 


.CSISPC 


345 


— 


9.4.8 


Calls the CSI in special mode. 
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Summary of Programmed Requests 



Mnemonic 



*.CSTAT 

.DATE 
*. DEVICE 

. DSTATUS 

.EXIT 

.FETCH 
.GTIM 
.GTJB 
.HERR 

.HRESET 

.INTEN 



.LOCK 



. MFPS 
*.MRKT 

.MTPS 

*.MWAIT 
.PRINT 

♦.PROTECT 



EMT & 
Code 



375 



375 

342 

350 

343 
375 
375 
374 

357 



27 



14 



346 



375 



374 
351 

375 



21 

20 
5 



22 



11 



31 



Section 



9.4.9 

9.3.1.1 

9.4.11 

9.4.12 

9.4.14 

9.4.15 
9.4.16 
9.4.17 
9.4.18 

9.4.19 

9.3.1.2 



9.4.20 



9.3.1.3 
9.4.22 

9.3.1.3 

9.3.23 
9.4.24 

9.4.25 



Purpose 



Returns the status of 
Indicated. 

Moves the current date 
into R0. 



the channel 
information 



Allows user to turn off device 
interrupt enable in F/B upon 
program termination. 

Returns the status of a particular 
device. 

Exits the user program and returns 
control to the Keyboard Monitor. 

Loads device handlers into memory. 

Gets time of day. 

Gets parameters of this job. 

Specifies termination of the job on 
fatal errors. 

Terminates I/O transfers and does a 
.SRESET operation. 

Notifies monitor that an interrupt 
has occurred and to switch to 
"system state" , and sets the 
processor priority to the correct 
value . 

Makes the monitor User Service 
Routines (USR) permanently resident 
until .EXIT or .UNLOCK is executed. 
The user program is swapped out if 
necessary. 

Reads the priority bits in the 
processor status word (does not 
read the condition codes) . 

Marks time; i.e., sets 
asynchronous routine to occur after 
a specified interval. 



Sets the priority bits, 
codes, and T bit in the 
status word. 



condition 
processor 



Waits for messages to be processed. 

Outputs an ASCII string to the 
terminal. 

Requests that vectors in the area 
from 0-476 be given exclusively to 
this job. 
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Summary of Programmed Requests 



Mnemonic 



.PURGE 
.QSET 

.RCTRLO 
.REGDEF 

.RELEAS 

*.RSUM 

.SERR 
.SETTOP 

.SFPA 
.SPFUN 
*.SPND 
.SRESET 
.SYNCH 

*.TLOCK 

.TRPSET 
*.TWAIT 
. UNLOCK 

. .VI. . 
..V2.. 

.WAIT 



EMT & 
Code 



Section 



374 
353 

355 

343 

374 

374 
354 

375 
375 
374 
352 



374 

375 
375 
347 



30 
32 



374 



3 

24 



9.4.26 
9.4.27 

9.4.28 

9.3.1.4 

9.4.31 
9.4.39 

9.4.18 
9.4.36 

9.4.37 
9.4.38 
9.4.39 
9.4.40 
9.3.1.5 

9.4.41 

9.4.42 
9.4.45 
9.4.20 

9 . 3 . 1 . 6 
9.3.1.6 

9.4.46 



Purpose 



Clears out a channel. 

Expands the size of the monitor I/O 
queue . 

Enables output to the terminal. 

Defines the PDP-11 general 
registers. 

Removes device handlers from 
memory . 

Causes the main line of the job to 
be resumed where it was suspended 
with .SPND. 

Inhibits most fatal errors from 
causing the job to the aborted. 



Specifies the 
location to be 
program. 



highest memory 
used by the user 



Sets user interrupt for floating 
point processor exceptions. 



Performs special functions 
magtape and cassette units. 



on 



Causes the running job 
suspended. 



to be 



Resets all channels and releases 
the device handlers from memory. 

Enables user program to perform 
monitor programmed requests from 
within an interrupt service 
routine. 

Indicates if the USR is currently 
being used by another job and 
performs a .LOCK if available. 

Sets a user intercept for traps to 
locations 4 and 10. 



Suspends the running job 
specified amount of time. 



for 



Releases USR if a LOCK was done. 
The user program is swapped in if 
required. 



Enables expansions 
Version 1 format. 

Enables expansions 
Version 2 format. 



to 



occur in 



to occur 



in 



Waits for completion of all I/O on 
a specified channel. 
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Requests requiring the USR (as explained in Section 9.2.5) differ 
between the Single- Job and F/B Monitors. Table 9-2 indicates which 
requests require the USR to be in memory. Those requests marked by an 
asterisk are Version 2 macros only. The CLOSE request on non-file 
structured devices (LP, PP, TT, etn.) does not require the USR under 
either monitor. 
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Table 9-2 
Requests Requiring the USR 



Request 


F/B 


Single- Job 


*.CDFN 


No 


Yes 


*. CHAIN 


No 


No 


*.CHCOPY 


No 


N/A 


.CLOSE (see Note 1) 


Yes 


Yes 


*.CMKT 


No 


N/A 


*.CNTXSW 


No 


N/A 


.CSIGEN 


Yes 


Yes 


.CSISPC 


Yes 


Yes 


*.CSTAT 


No 


N/A 


.DELETE 


Yes 


Yes 


♦.DEVICE 


No 


N/A 


.DSTATUS 


Yes 


Yes 


.ENTER 


Yes 


Yes 


.EXIT 


No 


No 


.FETCH 


Yes 


Yes 


*.GTIM 


No 


No 


* . GT JB 


No 


No 


*.HERR 


No 


No 


.HRESET 


No 


Yes 


.LOCK (see Note 2) 


Yes 


Yes 


.LOOKUP 


Yes 


Yes 


*.MRKT 


No 


N/A 


*.MWAIT 


No 


N/A 


.PRINT 


No 


No 


*. PROTECT 


No 


N/A 


*. PURGE 


No 


No 


.QSET 


Yes 


Yes 


.RCTRLO 


No 


No 


* . RCVD/RCVDC/RCVDW 


No 


N/A 


. READ/.READC/.READW 


No 


No 


.RELEAS 


Yes 


Yes 


.RENAME 


Yes 


Yes 


. REOPEN 


No 


No 


*.RSUM 


No 


N/A 


. SAVES TATUS 


No 


No 


* . SDAT/SDATC/SDATW 


No 


N/A 


*.SERR 


No 


No 


.SETTOP 


No 


No 


*.SFPA 


No 


No 


*.SPFUN 


No 


No 


*.SPND 


No 


N/A 


*.SRESET 


No 


Yes 


*.TLOCK (see Note 3) 


No 


No 


*.TRPSET 


No 


No 


.TTINR/.TTYIN 


No 


No 


.TTOUTR/.TTYOUT 


No 


No 


*.TWAIT 


No 


N/A 


.UNLOCK 


No 


NO 


.WAIT 


No 


NO 


.WRITE/WRITC/WRITW 


No 


No 
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Note 1: Only if channel was opened via .ENTER. 

Note 2: Only if USR is in a swapping state. 

Note 3: Only if USR is not in use by the other job, 



9.3.1 System Macros 

The following five macros are included in the system macro library, 
but are not programmed requests in that they cause no EMT instruction 
to be generated: 

.DATE .SYNCH 
.INTEN ..V2.. 
. REGDEF 



They can be used in the same manner as the other macro calls ; 
explanations follow. 



their 



.DATE 



9.3.1.1 .DATE 

This request moves the current date information from the system date 
word into RO. The date word returned is in the following format: 



Bit: 



14 



10 9 



5 4 





MONTH 
(1-12.) 


DAY 
(1-31.) 


YEAR-72 (DECIMAL) 



Macro Call: 
Errors : 



.DATE 



No errors are returned. A zero result in RO indicates that no DATE 
command was entered. 
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.INTEN 



9.3.1.2 .INTEN 

This request is used by user program interrupt service routines to: 

1. Notify the monitor that an interrupt has occurred and to 
switch to "system state", 

2. Set the processor priority to the correct value. 

In Version 2 of RT-11, all external interrupts cause the processor to 
go to level 7 (see Appendix H) . .INTEN is used to lower the priority 
to the value at which the device should be run. On return from 
.INTEN, the device interrupt can be serviced, at which point the 
interrupt routine returns via an RTS PC. It is very important to note 
that an RTI will not return correctly from an interrupt routine which 
specifies an .INTEN. 

Macro Call: .INTEN .priority, pic 

where: .priority is the processor priority at which the user 

wishes to run his interrupt routine. 

pic is an optional argument which should be 
non-blank if the interrupt routine is written 
as a PIC (position independent code) routine. 
If the routine does not have to be PIC, it is 
recommended that the PIC field be left blank; 
the non-PIC version is slightly faster than 
the PIC version. 

The user is advised to read Appendix H for more details concerning the 
use of .INTEN and .SYNCH. 

Errors : 

None . 

Example : 

Refer to Section 9.3.1.5, .SYNCH, for an example. 
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.MFPS/.MTPS 



9.3.1.3 .MFPS/.MTPS 

The .MFPS and .MTPS macro calls allow processor-independent user access 
to the processor status word. 

The .MFPS call is used to read the priority bits only; condition codes 
are destroyed during the call and must be directly accessed (using con- 
ditional branch instructions) if they are to be read in a processor- 
independent manner. 



Macro Call: 



.MFPS .addr 



where: .addr is the address into which the processor status 

is to be stored; if .addr is not defined, the 
value is returned on the stack. Note that only 
the priority bits are significant. 



The .MTPS call is used to set the priority, condition codes, and T 
with the value designated in the call. 



bit 



Macro Call: .MTPS .addr 



where : . addr 



is the address of the word 
processor status word; if 
the processor status word 
stack. Note that the high 
set to zero when .addr is 
not present, the user shou 
the appropriate value. In 
whole word on the stack is 
status word. 



to be placed in the 
•addr is not defined, 
is taken from the 

byte on the stack is 
present. If .addr is 
Id set the stack to 

either case, the 

put in the processor 



The contents of RO are preserved across either call. 

Errors: 

None. 
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Example: 



.MCALL , .V2..,.REG0EF,.MFPS,.MTPS,.EXIT 

..VS.. 

.REGDEF 



START! JSR PC#PICKO 



IPICK A QUEUE ELEMENT 



.EXIT 



PICKQI 


.MFP5 




MQV #QHEAD,R« 




.MTP8 #340 




MOV #R4,R5 




BED 10$ 




MOV #R5,*RA 




.MTPS 




CLZ 


I0$t 


RTS PC 


QHEADl 


.WORD Ql 



ISAVE PREVIOUS PRIORITY IN SP 
JPOINT TO QUEUE HEAD 
IRAISE PRIORITY TO 7 
IRS POINTS TO NEXT ELEMENT 
»NO MORE ELEMENTS AVAILABLE 
JRELINK THE QUEUE 
(RESTORE PREVIOUS PRIORITY 
IFLAG SUCCESS 

IQUEUE HEAD 



ITHREE QUEUE ELEMENTS 
Qi« .WORD 03,0,0 
QS> .WORD 03,0,0 
Q3I .WORD 0,8,0 

.END START 
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.REGDEF 



J 9.3.1.4 . REGDEF 



This macro call defines the PDP-11 general registers as RO through R5,, 
SP, and PC. 

Macro Call: .MCALL .REGDEF,... 
. REGDEF 

Errors : 

None. 

Example : 

Refer to the example for the .SYNCH request. Appendix D shows the 
expansion of .REGDEF. 



.SYNCH 



9.3.1.5 . SYNCH 

This macro call enables the user program to perform monitor programmed 
requests from within an interrupt service routine. Unless a .SYNCH is 
used, issuing programmed requests from interrupt routines is not 
supported by the system and should not be performed. .SYNCH, like 
.INTEN and .DATE, is not a programmed request and generates no 
EMT instructions . 

Macro Call: .SYNCH .area 

where: .area is the address of a seven-word area which the 

user must set aside for use by .SYNCH. The 
7-word block appears as: 

Word 1 RT-11 maintains this word; its 
contents should not be altered by 
the user. 

Word 2 The current job's number. This can 
be obtained by a .GTJB call. 

Word 3 Unused . 
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Word 
Word 



Word 
Word 



Unused. 

RO argument. When a 

return is made from 

contains this argument. 

Must be -1. 

Must be 0. 



successful 
. SYNCH , RO 



Note: 

•SYNCH assumes that the user has not pushed anything on the stack 
between the .INTEN and .SYNCH calls. This rule must be observed for 
proper operation. 



Errors : 

The monitor returns to the location immediately following the .SYNCH 
if the .SYNCH was rejected. The routine is still unable to issue 
programmed requests, and R4 and R5 are available for use. Errors 
returned are due to one of the following: 



1. 



2. 



3. 



Another .SYNCH which specified the same 7-word block is still 
pending. 

An illegal job number was specified in the second word of the 
block. The only currently legal job numbers are and 2. 



If the job has been aborted or for some reason is 
running, the .SYNCH will fail. 



no 



longer 



Normal return is to the word after the error return with the routine 
in user state and thus allowed to issue programmed requests. RO 
contains the argument which was in word 5 of the block. RO and Rl are 
free to be used without having to be saved. (R4 and R5 are not free.) 
Exit from the routine should be done via an RTS PC. (Refer to Appendix 
H, Section H.1.4, and to the RT-11 Software Support Manual , 
Section 6.4.) 



Example: 



START| 



.MCALU 
..V2.. 

.Rfc'GOEF 

.MCALL 
MOV 

.gtjh 

MQV 



.SYNCH 
BR 



..va..,.»eeoFF 



.GTJB, , ,INTPN,.WRTTf,.SVNCH,.FXIT,.PRTNT 



#ABEA,R5 

fR«!) ,SYNBLK*8 



INTRPTl .INTPN 5 



•synslk 

SYNFAIL 



JOUTPUT OF .GTJB GOES HE*E 

»GFT JOB NUMBER 

(STORE THE JOB NUMUl* TNTO SYNCH BLOCK 

»IN "ERE WE SET UP INTERRUPT 

IPR0CE8SINR, AND START UP THE 

INTERRUPTING DEVICE'. 



»G0 INTO SYSTEM STATF 
IRUN AT LEVEL FIVE 
I INTERRUPT PROCESSING — 
INOTHINQ C»N GO ON STACK 
ITIME TO WRITE A BUFFER 
fSYNCH BLOCK IN USE 
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IRFTURN HfRE AT PRIORITY 0*. NOTEl .SYNCH HOES RTI 

,W«ITC #A»EA, THAN, BUFF, WCNT»#CRTN1 ,«LK 

»WPITE A BUFFER 



BCS WTPATL 



PT3 PC 

synbikI .word a 

.WORO <* 

.woro 

.WORO CI 

, wOrO % 

'.WORO -1,0 
SYNFARt • 



fF»ILEr> somehow 

IRF-TNTTIALI7.E FOR MflRF 
HNTPRWUPTS AN|P» EXIT 

»JPB NUM*EP 



»Rfl CONTAINS 5 ON SUCCESSFUL 

>SYNCH 

»SFT UP FOP MONITOR 



VI.. /..V2 



9.3.1.6 . .VI. ./. .V2. . 

Any program that uses system MACROS must specify the version format 

(Version 1 or Version 2) in which the macro calls are to be expanded. 

Assembly errors at macro calls will result if the proper version 
designation is not made. 

The ..VI.. macro call enables all macro expansions to occur in Version 
1 format. (Note that any requests marked with an asterisk in Table 
9-1 are not valid as Version 1 requests, and thus will be flagged as 
errors if they are assembled in Version 1 form. ) 



Macro Call: 



.MCALL ..VI. 
..VI.. 



This causes all macros in the program to be assembled in Version 1 
form and the symbol ...VI to be defined. User programs should not use 
this symbol. The ..VI.. macro expands into: 



. . .Vl=l 

To cause all macro expansions to occur in Version 2 format, the 
macro call is used. Using ..V2.. causes the symbol . . ,V2 to 
defined. Likewise, user programs should not use this symbol. 



.V2, 



be 



Macro Call: 



.MCALL 
. .V2. . 



.V2. 



The ,.V2.. macro expands into: 



.MCALL , 
. . .V2=l 



.CMl, . . .CM2, . . .CM3, . . .CM4 



January 1976 
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Note: 

It is possible that user programs will exist in which both Version 1 
and Version 2 macros are present. To allow proper assembly, the user 
should include the statements: 

.MCALL . .VI.. , . . .CM1, . . .CM2, . . .CM3,. . .CM4 
..VI. . 

to define the utility macros (CMl, CM2 , etc.) used by other Version 2 
macros. This causes all macros which existed in Version 1 to assemble 
in Version 1 format, while those macros new to Version 2 are correctly 
generated as Version 2 macros. Note that in this case a macro which 
existed in Version 1 (such as .READ) will expand in the Version 1 
format. 

Run-time or assembly errors will occur if both the ..VI.. and ..V2.. 
macro calls are used in a program. 

Example: 

All examples in Chapter 9 illustrate the Version 2 format. Users are 
urged to use the ..V2.. macro call in their programs. 

9.4 PROGRAMMED REQUEST USAGE 

This section provides a description of each of the programmed requests 
alphabetically. The following parameters are commonly used as 
arguments in the various calls: 

.addr an address, the meaning of which depends on the 
request being used 

.area a pointer to the EMT argument list (for those 
requests which require a list); see Section 9.2.3 

.blk a block number specifying the relative block in a 

file where an I/O transfer is to begin 

•buff a buffer address specifying a memory location into 

or from which an I/O transfer is to be performed 

.chan a channel number in the range 0-377 (octal) 

.crtn the entry point of a completion routine; see 
Section 9.2.8 

.count file number for magtape/cassette operations (see 
Appendix H) ; if this argument is blank, a value of 
is assumed 

•dblk the address of a four-word RAD50 descriptor of the 

file to be operated upon; see Section 9.2.2 

.num a number, the value of which depends on the 

request 

.went a word count specifying the number of words to be 

transferred to or from the buffer during an I/O 
operation 

Additional information concerning these parameters (and others not 
defined here) is provided as necessary under each request. 
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9.4.1 .CDFN 

The .CDFN request is used to redefine the number of I/O channels. 
Each job, whether foreground or background, is initially provided with 
| 16 (decimal) I/O channels, numbered 0-15. .CDFN allows the number to 
be expanded to as many as 255 (decimal) channels. 

Note that .CDFN defines new channels; the previously-defined channels 
are not used. Thus, a .CDFN for 20 (decimal) channels (while the 16 
original channels are defined) causes only 20 I/O channels; the space 
for the original 16 is unused. 

Note that if a program is overlaid, channel 15 is used by the overlay 
handler and should not be modified. (Other channels can be defined and 
used as usual.) 

Macro Call: .CDFN .area, .addr, .num 

where: .addr is the address where the I/O channels begin 

.num is the number of I/O channels to be created 

Request Format: 

■► .area: 



R0 



15 



.addr 



.num 



The space used to contain the new channels is taken from within the 
user program. Each I/O channel requires 5 words of memory. Thus, the 
user must allocate 5*N words of memory, where N is the number of 
channels to be defined. 

It is recommended that the .CDFN request be used at the beginning of a 
program, before any I/O operations have been initiated. If more than 
one .CDFN request is used, the channel areas must either start at the 
same location or not overlap at all. The two requests .SRESET and 
.HRESET cause the user's channels to revert to the original 16 
channels defined at program initiation. Hence, any .CDFNs must be 
reissued after using those directives. 



Errors i 

Code 


Example: 

.MCALl 
..V2,. 

.REGDEF 
.MCALl 

STARTJ .CDFN 
BCS 
.PRINT 
.EXIT 

BA0C0FJ .PRINT 
.EXJT 

M3G1I .ASCIZ 

.EVEN 

M9G2I . ASCIZ 

January 1976 



Explanation 

An attempt was made to define fewer channels than 
already exist. 



,.V2.., .REGDEF 

.CDFN, .PRINT,. EXIT 

#R0UST,#CHANL.,»«0, 

BADCDF 

#MSGl 

#MSG2 

/.CDFN O.K./ 

/BAD .CDFNZ 
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.EVEN 

MLXSTI .SIM 3 »6MT ARGUMENT LIST 

CHANU .IBLKW HI. *5 iROOM FOR CHANNELS 

,EN0 START 

The example defines 40 (decimal) channels to start at location CHANL, 
An error occurs if 40 or more channels are already defined. 
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9.4.2 .CHAIN 

This request allows a background program to pass control directly to 
another background program without operator intervention. Since this 
process may be repeated, a large "chain" of programs can be strung 
together. 

The area from locations 500-507 contains the device name and file name 
(in RAD50) to be chained to, and the area from locations 510-777 is 
used to pass information between the chained programs. 

Macro Call: .CHAIN 



Notes: 



No assumptions should be made concerning which areas of 
memory will remain intact across a .CHAIN. In general, 
500-777 is the only area guaranteed to be preserved across 
a .CHAIN. 

I/O channels are left open across a .CHAIN for use by the new 
program. However, I/O channels opened via a .CDPN request 
are not available in this way. Since the monitor reverts to 
to the original 16 channels during a .CHAIN, programs which 
leave files open across a .CHAIN should not use .CDFN. 
Furthermore, non-resident device handlers are released during 
a .CHAIN, and must be .FETCHed again by the new program. 

A program can determine whether it was CHAINed to or RUN from 
the keyboard by examining bit 8 of the JSW. This bit is on 
during program execution only if the program was entered via 
CHAIN. If a program normally loads into area 500-777, bit 8 
of the JSW should be set during program assembly. This causes 
the monitor to load the area properly. if the bit is not set, 
locations 500-777 are preserved from the chaining program, 
causing the new program to malfunction. 



Errors : 



.CHAIN is implemented by simulating the monitor RUN command (described 
in Chapter 2) , and can produce any errors which RUN can produce. If 
an error occurs, the .CHAIN is abandoned and the Keyboard Monitor is 
entered. 



When using .CHAIN, care should be taken for initial stack placement, 
since the program being "chained to" is started. The Linker normally 
defaults the initial stack to 1000 (octal); if caution is not observed, 

the stack may destroy chain date before it can be used (see Chapter 2, 
the RUN command) . 
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Example : 



STARTl 



LQOPl 



CHPTRl 



.MCALL 

.REGDEF 
.MCALL 

MOV 

MOV 

,REPT 

MOV 

.SNDR 

,TT¥IN 

MQVB 

CMPB 

BNE 

CLRB 

.CHAIN 

.RAD50 

.RAD50 

.RAD50 

.END 



,,V2,,,,RE60EF 



.CHAIN, .TTVIN 

#580, Rl 
*CHPTR,R2 
4 
CR2)*,(R1)* 



R0,CRi>* 
RB,il2 
LOOP 
IRi)* 

/DK / 
/TECO / 
/SAV/ 

START 



»3ET UP TO CHAIN 

IDEVICE, FILE NAME TO 30B-3JI 



INON GET A COMMAND LINE 
IAND PASS IT TO THE JOB 

UN LOCATIONS 512 AND UP 
ILOOP UNTIL LINE FEED 
IPUT IN A NULL BYTE 



.CHCOPY 



9.4.3 .CHCOPY (P/B only) 

The .CHCOPY request opens a channel for input, logically connecting it 
to a file which is currently open by the other job for either input or 
output. This request may be used by either the foreground or the 

background. .CHCOPY must be done before the first .READ or .WRITE. 

Macro Call: .CHCOPY .area, .chan, .ochan 



where : . chan 



is the channel which the job will use to read 
the data. 



, ochan 



is the channel number of the other job 
is to be copied 



which 



Request Format: 



RO * .area: 



13 



.chan 



I . ochan 



.CHCOPY is legal only on files which are on disk or DECtape; however, 

no errors are detected by the system if another device is used. (To 
close a channel following use of .CHCOPY, use either the .CLOSE or 
. PURGE request . ) 

Notes : 

1. If the other job's channel was opened via an .ENTER in order 
to create a file, the copier's channel indicates a file which 
extends to the highest block that the creator of the file had 
written at the time the .CHCOPY was executed. 

January 1976 9-28 



Programmed Requests 



2. A channel which is open on a nonf ile-structured device 
should not be copied, because intermixture of buffer requests 
may result. 

3. A program can write to a file (which is being created by the 
other job) on a copied channel just as it could if it were 
the creator. When the copier's channel is closed, however, 
no directory update takes place. 



Errors : 



Code 



Ex planation 

Other job does not exist, does not have 
enough channels defined, or does not have the 
specified channel (.ochan) open. 

Channel (.chan) already open. 



Example : 



In this example, .CHCOPY is used to read data currently being written 
by the other job. The correct block number and channel to read is 
obtained by a .RCVDW command. The channel number will be in MSG+4. 



STl 



NOJOBt 

BUSYl 
RQERRJ 



AREAI 

MSGl 

BU*FI 

MSGil 

MSG2S 

M3GJI 

OKMSGl 

.EVEN 



,MC*U 

M'*ll 

.BEG06F 
.MCALL 

.PURGE 

.RCVOW 

scs 

.CHCOPY 

BC3 

.READW 

8CS 

.PRINT 

.EXIT 

.PRINT 

.EXIT 

.PRINT 

.EXIT 

.PRINT 

.EXIT 

.BLKW 

.BLKW 

,BLKM 

.A8CIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.EXIT 

.END 



.,V2,,,,REG0EF 



,CHCOPV,,RCVDW,,PURGE,,READW,.EXIT,,PRINT 



«0 
#AREA,#MSG,*2 

NOJOB 

#AREA,#B,MSG*« 
BUSY 

#AREA,#0,#&UPF. 
ROERR 

iOKMSG 

#MSGJ 
#MSG2 

#MS63 



5 
5 
25*. 

/NO JOB!/ 
/BUSYl/ 
/REAO ERROR/ 
/READ OK/ 



(MAKE SURE WE HAVE CLEAR 

(CHANNEL 

IREAD TWO WORDS, BLOCK « 

MND CHANNEL 

»N0 JOB THERE 
(CHANNEL # IS IN THERE 

IBUT BUSY 
»256,,MSG*2 JGET TmE CQRKECT 



BLOCK 



ST 
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9.4.4 .CLOSE 

The .CLOSE request terminates activity on the specified channel and 
frees it for use in another operation. The handler for the associated 
device must be in memory. 

Macro Call: .CLOSE .chan 

Request Format: 

RO * 



• chan 



A .CLOSE is required on any channel opened for either input or output. 
A .CLOSE request specifying a channel that is not opened is ignored. 

A .CLOSE performed on a file which was opened via .ENTER causes the 
device directory to be updated to make that file permanent. A file 
opened via .LOOKUP does not require any directory operations. If the 
device associated with the specified channel already contains a file 
with the same name and extension, the old copy is deleted when the new 
file is made permanent. When an entered file is .CLOSEd, its 
permanent length reflects the highest block written since it was 
entered; for example, if the highest block written is block number 0, 
the file is given a length of 1; if the file was never written, it is 
given a length of 0. If this length is less than the size of the area 
which was allocated at .ENTER time, the unused blocks are reclaimed as 
an empty area on the device. 



Errors : 

.CLOSE does not return any errors. If the device handler for 
operation is not in memory, a fatal monitor error is generated. 



the 



Example : 

An example which illustrates the .CLOSE request follows the discussion 
of the .WRITW request in Section 9.4.47. 
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9,4.5 .CMKT (F/B only) 

The .CMKT request causes one or more outstanding mark time requests to 
be cancelled (mark time requests are discussed in Section 9.4.22). 



Macro Call: 
where : 



.CMKT .area, .id, .time 
.id 



is a number used to identify each mark 
request to be cancelled. If more than one 
time request has the same .id, that with 
earliest expiration time is cancelled. If 
0, all nonsystem mark time requests (i.e., 
the range 1-177377) for the issuing job are can- 
celled. 



time 

mark 

the 

id = 

in 



.time 



Request Format: 

R0 ^ .area: 



Notes : 
1. 

2. 
Errors : 



is the pointer to a two-word area in which the 
Monitor will return the amount of time 
remaining in the cancelled request. The first 
word contains the high-order time, the second 
contains the low-order. If an address of is 
specified, no value is returned. If .id ■ 0, 
the .time parameter is ignored and need not be 
indicated. 



23 



.id 



.time 



Cancelling a mark time request 
element for other uses . 



frees the associated queue 




A mark time request can be converted into a timed wait by 
issuing a .CMKT followed by a .TWAIT, and specifying the same 
.time area. 



Explanati on 

The .id was not zero; a mark time with that 
identification number could not be found (implying 
that the request was never issued or that it has 
already expired) . 



9-31 



January 1976 



Programmed Requests 

Example : 

See the example following the description of the .MRKT request. 



.CNTXSW 



9.4.6 .CNTXSW (F/B only) 

A context switch is an operation performed when a transition is made 

from running one job to running the other. The .CNTXSW request is 

used to specify locations to be included in the context switch. 



Macro Call: 
where : 



.CNTXSW .area, .addr 

. addr is a list of addresses terminated by a zero 
word. The addresses in the list must be even 
and: 

a. in the range 2-476, or 

b. in the user job area, or 

c. in the I/O page (addresses 
160000-177776) . 



Request Format: 



R0 =^ .area: 



33 



. addr 



The system always saves the parameters it needs to uniquely identify 
and execute a job, including all registers, and the locations: 



34/36 
40-52 



Vector for TRAP instruction 
System Communication Area 



If an .SFPA request (Section 9.4.37) has been executed with a non-zero 
address, all floating point registers and the floating point status 
are also saved. 



It is possible that both jobs 
particular location and that 
context switch operations. For 
instruction to perform some 
error messages) , it must set up 
internal IOT trap handling routi 
wish to use IOT, the IOT vector 
location for the job which is 
22 in the .CNTXSW list for both 



may want to share the use of a 
location is not included in normal 
example, if a program uses the IOT 
internal user function (such as print 
the vector at 20 and 22 to point to an 
ne. If both foreground and background 
must always point to the proper 
executing. Including locations 20 and 
jobs will accomplish this. 



If .CNTXSW is issued more than once, only the latest list is used; 
the previous address list is discarded. Thus, all addresses to be 
switched must be included in one list. If the address (.addr) is 
zero, no extra locations are switched. The list may not be in an area. 
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into which the USR swaps, nor may it be modified while a job 
running. 



is 



Errors : 

Code 


Example : 



Explanation 

One or more of the above conditions was violated. 



In this example, .CNTXSW request is used to specify that locations 20 
and 22 (IOT vector) and certain necessary EAE registers be context 
switched. This allows both jobs to use IOT and the EAE simultaneously 
yet independently. 



STARTJ 



.MCALL 
• « * 2 , , 

.REGDEF 

MQV 

, CNJXSW 

BCC 

.PRINT 

.EXIT 



1SI 



.PRINT 
• EXIT 

SWAPL3I ,M0RD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 

USTI .BYTE 
.WORD 

ADOERRI .A8CIZ 

.EVEN 

CNTOKJ .A3CIZ 

.EVEN 

.END 



,. V2,,,, REGDEF,. CNTX3W,, PRINT,, EX IT 
I CALL. FOR V2 MACROS 
fOEPINE REGISTERS 

#LI8T,R0 »3ET R0 TO OUR OWN CIST 

,#8WAPLS |THE LIST OF ADDR3 IS 
IAT 3WAPLS, 

1$ 

iAODERR MDORESS ERR0RC8H0ULD NOT 

I0CCUR) 



KCNTOK 

20 

22 

177302 

17730« 

177310 



0,33 



/ADDRESSING ERROR/ 

/CONTEXT SWITCH 0.K,/ 

STA.RT 



IADDRESSE3 TO INCLUDE IN LIST 



JFUNCTION CODE WORD 

ITHE MACRO FILLS THIS ONE. 



.CSIGEN 



9.4.7 .CSIGEN 

The .CSIGEN request calls the Command String Interpreter (CSI) in 
general mode to process a standard RT-11 command string (see Chapter 2 
for the description of a standard command string). In general mode, 
all file .LOOKUPS and .ENTERS as well as handler .FETCHs are 
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performed. When called in general mode, the CSI closes channels 0-10 
(octal) . 

Macro Call: .CSIGEN .devspc, .defext, .cstring 



where: .devspc 
.defext 

. cstring 



is the address of the memory area where the 
device handlers (if any) are to be loaded. 

is the address of a four-word block which 
contains the RAD50 default extensions. These 
extensions are used when a file is specified 
without an extension. 

is the address of the ASCIZ input string or a 
#0 if input is to come from the console 
terminal. (In a F/B environment only, if the 
input is from the console terminal, an 
.UNLOCK of the USR is automatically 
performed, even if the USR is locked at the 
time.) If the string is in memory, it must 
not contain a <CRXLF>, but must terminate 
with a zero byte. If the .cstring field is 
left blank, input is automatically taken from 
the console terminal. 

.CSIGEN loads all necessary handlers and opens the files as specified. 
The area specified for the device handlers must be large enough to 
hold all the necessary handlers simultaneously. If the device 
handlers exceed the area available, the user program may be destroyed. 
The system, however, is protected from this. 



When the EMT is complete, register points to 
location above the handlers. 



the first available 



The four-word block pointed to by .defext is arranged as: 

Word 1: default extension for all input channels 

Words 2, 3, and 4: default extensions for output channels 0,1,2 

respectively 

If there is no default for a particular position, the associated word 
must contain a zero. All extensions are expressed in Radix 50. For 
example, the following block can be used to set up default extensions 
for a macro assembler: 



DEFEXT: 



.RAD50 
.RAD50 
.RAD50 
.WORD 



"MAC" 
"OBJ" 
"LST" 




In the command string: 

*DT0 : ALPHA, DTI :BETA=*DT2 : INPUT 

the default extension for input is MAC; for output, OBJ and LST. The 
following cases are legal: 

*DT0:OUTPUT= 
*DT2:INpUT 

In other words, the equal sign is not necessary in the event that only 

input files are specified. 
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When control returns to the user program after a call to .CSIGEN, all 
the specified files have been opened for input and/or output. The 
association is as follows: the three possible output files are 
assigned to channels 0, 1, and 2; the six input slots are assigned to 
channels 3 through 10. A null specification causes the associated 
channel to remain inactive. For example, in the following string: 

*,LP:«F1,P2 

channel is inactive since the first slot is null. Channel 1 is 
associated with the line printer, and channel 2 is inactive. Channels 
3 and 4 are associated with two files on DK:, while channels 5 through 
10 are inactive. The user program can determine whether a channel is 
inactive by issuing a .WAIT request on the associated channel, which 
returns an error if the channel is not open. 

Switches and their associated values are returned on the stack; see 
Section 9.4.8.1 for a description of the way switch information is 
passed. 

Errors : 

If CSI errors occur and input was from the console terminal, an error 
message describing the fault is printed on the terminal and the CSI 
retries the command (these messages appear in Section 9.4.8.1). If the 
input was from a string, the carry bit is set and byte 52 contains the 
error code. The errors are: 

Code Explanation 

Illegal command (bad separators, illegal filename, 
command too long, etc.). 

1 A device specified is not found in the system tables. 

2 Unused. 

3 An attempt to .ENTER a file failed because of a full 
directory. 

4 An input file was not found in a .LOOKUP. 
Example: 

This example uses the general mode of the CSI in a program to copy an 
input file to an output file. Command input to the CSI is from the 
console terminal. 

.HCAU „,V2 t .,.REGDEF 
..V2., 

.REGDEF 

.MCALL .CSIGEN,, RE ADW,, PRINT,, EXIT,. WRITW,, CLOSE,, 8RE3ET 
ERRWQi52 

STARTI .CSIGEN #DSPACE , #DEXT >GET STRING FROM TERMINAL 

MOV R0,BUFF |R0 HAS FIRST FREE LOCATION 

CLR INBLK r INPUT BLOCK # 

MOV #LIST,R5 »EMT ARGUMENT. LIST 

REAOI .REAOW R5, #3, BUFF, #256., INBLK /READ CHANNEL 3 

BCC 2S |N0 ERRORS 

TSTB ##ERRWD >E0F ERROR? 

BEQ EOF lYES 

MOV fINERR,R0 
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1SI 
2SI 

NOERRl 
EOF! 



OEXTI 

BUFFI 

INBLKI 

LIST! 

INERRJ 

WTERRl 

DSPACE*, 



.PRINT 

CIR 

.EXIT 

.WRITW 

BCC 

MOV 

BR 

INC 

BR 

.CLOSE 

.CLOSE 

,SRE5£T 

BR 

.WORD 

.WORD 

.WORD 

.BLKk 

.A3CIZ 

.EVEN 

.ASCIZ 

.EVEM 

,END 



R0 



IERROR MESSAGE 
JHARD EXIT 



R5,#0,BUFF,#25*,,INBLK IWRITE THE BLOCK 



NOERR 

#*TERR,R0 

IS 

INBLK 

READ 

#0 

#3 

START 

0, 0, Z, 





5 

/INPUT ERROR/ 

/OUTPUT ERROR/ 



START 



INO ERROR WRITING 

IMARO OUTPUT ERROR 

IGET NEXT BLOCK 

H.OOP UNTIL DONE 

ICLQSE OUTPUT CHANNEL 

IANO INPUT CHANNEL 

IRELEASE HANDLER FROM MEMORY 

IGO FOR NEXT COMMAND LINE 

»NO DEFAULT EXTENSIONS 

II/Q BUFFER START 

^RELATIVE BLOCK TO READ/WRITE 

IEMT ARGUMENT LIST 



CHANDLER SPACE 



.CSISPC 



9.4.8 .CSISPC 

The .CSISPC request calls the Command String Interpreter in special 
mode to parse the command string and return file descriptors and 
switches to the program. In this mode, the CSI does not perform any 
handler fetches, .CLOSES, .ENTERS, or .LOOKUPS. 

Macro Call: .CSISPC .outspc, .defext, .cstring 



where: .outspc 



. defext 



is the address of the 39-word block to 
contain the file descriptors produced by 
.CSISPC. This area may overlay the space 
allocated to .cstring if desired. 

is the address of a four-word block which 
contains the RAD50 default extensions. These 
extensions are used when a file is specified 
without an extension. 
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.cstring is the address of the ASCIZ input string or a 
#0 if input is to come from the console 
terminal. If the string is in memory, it 
must not contain a <CRXLF> but must 
terminate with a zero byte. If .cstring is 
blank, input is automatically taken from the 
console terminal. 

The 39-word file description consists of nine file descriptor blocks 
(five words for each of three possible output files; four words for 
each of six possible input files) which correspond to the nine 
possible files (three output, six input) . If any of the nine possible 
filenames are not specified, the corresponding descriptor block is 
filled with zeroes. 

The five-word blocks hold four words of RAD50 representing 
devtfile.ext, and 1 word representing the size specification given in 
the string. (A size specification is a decimal number enclosed in 
square brackets [] , following the output file descriptor.) For 
example , 

*DT3 : LIST. MAC [15] =PR: 

Using special mode, the CSI returns in the first five word slot: 

16101 .RAD50 for DT3 

46173 .RAD50 for LIS 

76400 .RAD50 for T 

50553 .RAD50 for MAC 

00017 Octal value of size request 

In the fourth slot (starting at an offset of 36 (octal) bytes into 
.outspc) , the CSI returns: 

63320 .RAD50 for PR 

No file name 

Specified 


Since this is an input file, only four words are returned. 

Switches and their associated values are returned on the stack. See 
Section 9.4.8.1. 

Errors : 

Errors are the same as in general mode. However, since .LOOKUPS and 
.ENTERS are not done, the error codes which are valid are: 

Code Explanation 

Illegal command line 

1 Illegal device 



Example j 

This example illustrates the use of the special mode of CSI. This 
example could be a program to read a file which is not in RT-11 format 
to a file under RT-11. 
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,MC»LL ,,V2,,,.REGQEF 
..V2.. 

.REGDEF 

.MCALL . CSI 8PC,. PRINT,, EXIT,. ENTER,. CLOSE 

START! .CSISPC #QUTSPC,#DEXT,#CSTRNG IGET INPUT FROM A 

JSTRING IN MEMORY 

BCC 28 

MOV «8VNERR,R0 I3YNTAX ERROR 
iSJ .PRINT (ERROR MESSAGE 

.EXIT 
2*1 .ENTER #LIST,#0,#OUT5PC,#M, IENTER FILE UNDER BT-ti 

BCC SI 

MQV *ENM8G,RB IENTER FAILED 

BR II 
381 J|R RS, INPUT IROUTINE INPUT KILL USE 

ITHE INFORMATION AT 
l*0UTSPC+36 TO READ INPUT 
IFROM THE NONfRTli DEVICE. 
IINPUT IS PROCESSEO AND 
IWRITTEN VIA .WRITW REQUESTS 

.CLOSE #B IMAKE OUTPUT FILE PERMANENT 

.EXIT JAND EXIT PROGRAM 

CSTRNGI .ASCIZ "DTill RTFIL ,MAC«DT2 lOOS.MAC" 

.EVEN 
DEXTI ,WORO 0,B,0,0 »NO DEFAULT EXTENSIONS 
LISTl .BLKW 5 1LIST FOR EMT CALLS 

SYNERRI .ASCIZ "CSI ERROR" 
ENMSGI .ASCII "ENTER FAILED" 

.EVEN 
INPUTl RTS Rb 
OUTSPC*. IC9I LIST GOES HERE 

.END START 



9.4.8.1 Passing Switch Information 

In both general and special modes of the CSI, switches and their 
associated values are returned on the stack. A CSI switch is a slash 
(/) followed by any character. The CSI does not restrict the switch 
to printing characters, although it is suggested that printing 
characters be used wherever possible. The switch can be followed by 
an optional value, which is indicated by a : or 1 separator. The : 
separator is followed by either an octal number or by one to three 
alphanumeric characters, the first of which must be alphabetic, which 
are converted to Radix-50. The 1 separator is followed by a decimal 
value. Switches can be associated with files with the CSI. For 
example : 

*DK : POO/A, DT4 : FILE . OB J/A : 10 

In this case, there are two A switches. The first is associated with 
the input file DK:FOO. The second is associated with the input file 
DT4: FILE. OBJ, and has a value of 100(8). The stack output of the CSI 
is as follows: 
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Word # 



Value 



1 N 
(top of 
stack) 



Meaning 

Number of 
command string, 
were found. 



switches 
If N=»0, no 



found in 
switches 



Switch value 
and file number 



Switch value 
or next switch 



Even byte - 7-bit ASCII switch value. 

Bits 8-14 = Number (0-10) of the file 

with which the switch is 

associated. 
Bit 15 - 1 if the switch had a 

value . 
» if the switch had no 

value. 

If word 2 was less than 0, word 3 - 
switch value. if word 2 was 
greater than , this word is the 
next switch value (if it exists). 



For example, if the input to the CSI is: 

*FILE/B : 20 , FIL2/E-DT3 : INPUT/X » SY : 20 
on return, the stack is: 
Stack Pointer-* 



3 
101530 

20 
101530 

075250 

505 

100102 

20 



Three switches appeared. 

Last switch-X; with file 3, has a 

value. 

Value of switch X=20 

Next switch =X; with file 3, has a 

value . 

Next value of switch X-RAD50 code for 

SY. 

Next switch»E; associated with file 1, 

no value. 

Switch-B; associated with file and 

has a value. 

Value is 20. 



As an extended example, assume the following string was input for the 
CSI in general mode: 

*FILE[8],LP:,SY:FILE2[20]=PR:,DT1:IN1/B,DT2:IN2/M:7 
Assume also that the default extension block is: 
DEFEXT: 



.RAD50 
.RAD50 
.RAD50 
.RAD50 



'MAC 
•OP1" 
'OP2' 
•OP3' 



; INPUT EXTENSION 
; FIRST OUTPUT EXTENSION 
I SECOND OUTPUT EXTENSION 
; THIRD OUTPUT EXTENSION 



The result of this CSI call would be: 



1. A file named FILE. OP 1 is entered on channel on device DK; 
channel 1 is open for output to the device LP; a 20-block 
file named FILE2.0P3 is entered on the system device on 
channel 2 . 
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2. Channel 3 is open for input from paper tape; channel 4 is 
open for input from a file INI. MAC on device DTI; channel 5 
is open for input from IN2.MAC on device DT2. 

3. The stack contains switches and values as follows: 

Explanation 



2 
102515 

7 
2102 



2 switches found in string. 

Second switch is M, associated with 

Channel 5; has a numeric value. 

Numeric value is 7. 

Switch is B, associated with 

Channel 4; has no numeric value. 

If the CSI were called in special mode (Section 9.4.8), the stack 
would be the same as for the general mode call, and the descriptor 
table would contain: 



OUTSPC: 15270 


;.RAD50 


•DK« 


23364 


;.RAD50 


•PIL' 


17500 


;.RAD50 


i e i 


60137 


;.RAD50 


•OP1' 


10 


; LENGTH 


OF 8 BLOCKS 


46600 


;.RAD50 


•LP" 






75250 


;N0 NAME 


OR LENGTH SPECIFIED 


;.RAD50 


•SY' 


23364 


;.RAD50 


'FIL' 


22100 


;.RAD50 


■E2' 


60141 


;.RAD50 


•OP3' 


24 


; LENGTH 


OF 20 (DECIMAL) 


63320 




16077 


;.RAD50 


•PR' 


;.RAD50 


•DTI' 


35217 


;.RAD50 


•INI' 





;.RAD50 


i • 


50553 


;.RAD50 


'MAC 


16100 


I.RAD50 


•DT2' 


35220 


;.RAD50 


•IN2' 





;.RAD50 


i i 


50553 


7.RAD50 


•MAC 










(twelve more zero words 
are returned) 



Keyboard error messages which may occur from incorrect use of the CSI 
when input is from the console keyboard include: 



Message 

?ILL CMD? 
?FIL NOT FND? 



Meaning 

Syntax error. 

Input file was not found. 
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?DEV FUL? Output file will not fit. 

?ILL DEV? Device specified does not exist. 



Notes : 



1. In many cases, the user program does not need to process 
switches in CSI calls. However, the user at the console may 
inadvertently enter switches. In this case, it is wise for 
the program to save the value of the stack pointer before the 
call to the CSI, and restore it after the call. In this way, 
no extraneous values will be left on the stack. 

2. In the F/B System, calls to the CSI which require console 
terminal input will always do an implicit .UNLOCK of the USR. 
This should be kept in mind when using .LOCK calls. 




9.4.9 .CSTAT (F/B only) 

This request furnishes the user with information about a channel. It 
is supported only in the F/B environment; no information is returned 
in the Single- Job Monitor. 

Macro Call: .CSTAT .area, .chan, .addr 

where: .addr is the address of a 6-word block which is to 

contain the status 

Request Format: 

RO # .area: 



27 



.chan 



.addr 



The 6 words passed back to the user are: 

1. Channel status word (see Section 9.4.34) 

2. Starting block number of file (0 if sequential-access device 
or if channel was opened with a nonf ile-structured .LOOKUP or 
.ENTER) 

3. Length of file (no information if nonf ile-structured device 
or if channel was opened with a nonf ile-structured .LOOKUP or 
.ENTER) 

4. Highest block written since file was opened (no information if 
nonf ile-structured device) 

5. Unit number of device with which this channel is associated 

6. RAD50 of the device name with which the channel is associated 
(this is a physical device name, unaffected by any user name 

ASSIGNment in effect) 
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The fourth word (highest block) is maintained by the .WRITE requests. 
If data is being written on this channel, the highest relative block 
number is kept in this word. 



Errors : 

Code Explanation 

The channel is not open. 

Example : 

In this example, .CSTAT is used to determine the .RAD50 representation 
of the device with which the channel is associated. 

.MCALL ..V8. f ,,REG0EF,.eSIGEN,,C8TAT 

..vs.. 

.REGOEF 

.MCALL .PRINT, .EXIT 



STI .CSIGEN #DEVSDC,*DEFEXT (OPEN FILES 

.CSTAT #AREA,#0,#ADOR IGET THE STATUS 

(CHANNEL NOT OPEN 
(POINT TO UNIT * 
(UNIT • TO R0 
(MAKE IT RAD50 





BCS 


NOCHAN 




MOV 


#ADOR«10»R5 




MOV 


(R5)*,R0 




ADO 


CPC)*,R0 




.RAD50 


/ 0/ 




ADO 


(R3),R0 




MOV 


R0,OEVNAM 




.EXIT 




AREAI 


.BUKW 


5 


ADORI 


,BLKW 


6 


DEVNAMt 


,NQRD 





DEFEXTl 


.WORD 


0,010,0 


NOCHANI 


.PRINT 
.EXIT 


#M8S 


MSGl 


.ASCIZ 

• EVEN 


/NO OUTPUT 


DEVSDC* 


• 





(GET DEVICE NAME 

IDEVNAM HAS RA050 DEVICE NAME 

(EMT ARG LIST 

(AREA FOR CHANNEL STATUS 

ISTQRASE FOR DEVICE NAME 



.END 



ST 



.DELETE 



9.4.10 .DELETE 

The .DELETE request deletes a named file from an indicated device. 

Macro Call: .DELETE .area, .chan, .dblk, .count 
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where : . count 



Request Format : 



is used by magtape/cassette only, (Refer to 
Appendix H for more information concerning 
the magtape and cassette handlers.) 



RO ^ .area: 



.chan 



.dblk 



•count 



Note : 

The channel specified in the .DELETE request must not be in use when 
the request is made, or an error will occur. The file is deleted from 
the device, and an empty (UNUSED) entry of the same size is put in its 
place. A .DELETE issued to a nonfile-structured device is ignored 
.DELETE requires that the handler to be used be in memory at the time 
the request is made. When the .DELETE is complete, the specified 
channel is left inactive. 



Errors : 



Code 



1 



Explanation 

Channel is active 

File was not found in the device directory 



Example t 

This example uses the special mode of CSI to delete files. 

.MCALL ,.V2, t ,,REGDEF 
..V2,. 

.REGDEF 

.MCALL t iRESET,,C3I3PC, .DELETE,, PRINT, .EXIT 

STARTl .SRESET 



BR 
NOFILEI .AICIZ 

.EVEN 
DEFEXTl .RA050 

.WORD 
LIST! .BLKW 
OUTSPC", 
INSPC»,*36 

.BIKW 

.END 



JMAKE SURE CHANNELS 

I ARE FREE 
.CSISPC #0UTSPC,#0EFEXT fGET COMMAND LINE 

I TERMINAL DIALOG WAS 

I OT I FILE 
.DELETE #LIST,#0,#INSPC >USE CHANNEL TO 

I0ELETE THE FILE 

IWMICH IS AT THE 
„ „ IFIRST INPUT SLOT. 

BCC START |0K, LOOP AGAIN 

.PRINT iNOFILE »N0 SUCH FILE 

START 
/FILE NOT FOUND/ 



/MAC/ 
0,0, 
2 



39. 

START 



I.MAC INPUT EXTENSION 
JNO OUTPUT DEFAULTS 
IEMT ARG LIST 



INSPC is the address of the first input slot in the CSI input table. 
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.DEVICE 



9.4.11 .DEVICE (F/B Only) 

This request allows the user to set up a list of addresses to be 
loaded with specified values when a program is terminated. Upon an 
.EXIT or CTRL C, this list is picked up by the system and the 
appropriate addresses are set up with the corresponding values. This 
function is primarily designed to allow user programs to load device 
registers with necessary values. In particular, it is used to turn 
off a device's interrupt enable bit when the program servicing the 
device terminates. 

Macro Call: .DEVICE .area, .addr 

where: .addr is the address of the list of masks and 

words . 

Request Format: 



RO •> .area: 



14 



.addr 



The list is composed of address/value pairs and should be terminated 
by a address. Only one list can be active at a given time. If 
multiple .DEVICE requests are given, the last list specified is the 
one used. 



Note: 

When the job is terminated for any reason, the list is scanned once. 
At that point, the monitor disables the feature until another .DEVICE 
call is executed. Thus, background programs which are re-enterable 
should include .DEVICE as a part of the reenter code. 

Errors : 
None. 
Example : 

The following example shows how .DEVICE is used to disable interrupts 
from the AFC11 (A-D converter sub-system) . 

.MCAll ,.V2,,,.RICDEr 
,.V2.. 

,RE6D£F 

.MCAIL .DEVICE, .EXIT 

3TARTJ .DEVICE *LI8T 

.EXIT 
LIST! .BYTE e,U »EMT ARfi LIST 
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.WORD ATQD 
ATODJ 172570 


a 

•END START 



MOORESS 13 172570 

>JAM A INTO IT 

>THI3 TERMINATES THE LIST. 



.DSTATUS 



9.4.12 .DSTATUS 

This request is used to obtain information about a particular device. 

Macro Call: .DSTATUS .cblk, .devnam 



where: .cblk 



is the 4-word space used to store the status 
information. 



.devnam is the pointer to the RAD50 device name. 

.DSTATUS looks for the device specified by .devnam and, if found, 
returns four words of status starting at the address specified by 
.cblk. The four words returned are: 

1. Status Word 



Bits 


7-0: contain a number which identifies the device in 




question. 


The values (octal) currently defined 




are: 











= 


RK05 Disk 




1 


= 


TC11 DECtape 




2 


= 


Reserved 




3 


= 


Line Printer 




4 


= 


Console Terminal 




5,6 


= 


Reserved 




7 


= 


PC11 High-speed Reader 




10 


= 


PC11 High-speed Punch 




11 


= 


Magtape (TM11, TMA11) 




12 


= 


RF11 Disk 




13 


= 


TA11 Cassette 




14 


= 


Card Reader (CR11, CM11) 




15 


= 


Reserved 




16 


= 


RJS03/4 Fixed-head Disks 




17 


= 


Reserved 




20 


= 


TJU16 Magtape 




21 


= 


RP02, RP03 Disk 




22 


= 


RX01 Disk 



Bit 15: 



Bit 14: 
Bit 13: 
Bit 12: 



1= Random-access device (disk, DECtape) 

0= Sequential-access device (line printer, paper tape, 

card reader, magtape, cassette, terminal) 
1= Read-only device (card reader, paper tape reader) 
1= Write-only device (line printer, paper tape punch) 
1= Non RT-11 directory-structured device (magtape, 

cassette) 
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Bit 11: 1= Enter handler abort entry every time a job is aborted 
0= Handler abort entry taken only if there is an active 
queue element belonging to aborted job 

Bit 10: 1= Handler accepts .SPFUN requests (e.g., MT, CT, DX) 
0= .SPFUN requests are rejected as illegal 

2. Handler size. 

The size of the device handler, in bytes. 

3. Entry point. 

Non-zero implies the handler is now in memory? zero 
implies it must be .FETCHed before it can be used. 

4. Device size. 

I The size of the device (in 256-word blocks) for block- 

replaceable devices; zero for sequential-access devices. 

The device name may be a user-assigned name. 
| Refer to the RT-11 Software Support Manual for greater detail. 
Errors: 

Code Explanation 

Device not found in tables. 

Example : 

This example shows how to determine if a particular device handler is 
in memory and, if it is not, how to .FETCH it there. 

.MCALU .,VZ,,,,REGDIF 
,.V2,. 

.REGDEF 

.MCALL .DSTATU8,. PRINT,, EXIT,, FETCH 

STARTl .0STATU8 #C0RI,#FPTR »GET STATUS OP DEVICE 

BCC IS 

.PRINT #ILLDEV I0EVICE NOT IN TABLES 

.EXIT 

191 TST CORE+ft 119 DEVICE RESIDENT? 

BNE 28 

.FETCH #HNDUR,#FPTR INO, BET IT 

BCC 28 

.PRINT #FEFAIL IFETCH FARED 

.EXIT 

281 .PRINT »FECH0K 

.EXIT 

COREI .8L.KW « I08ATU8 GOES HERE 

FPTRI .RAD50 /OT0/ >DEVICE NAME 

.RADSi /FILE MAC/ IPILE NAME 

FEFAILI .ASCIZ /FETCH FAILED/ 

ILLOEVI .ASCIZ /ILLEGAL DEVICE/ 

EVEN 

FECHOKI IaSCIZ /FETCH O.K./ 

.EVEN 
HNDLR*. ^HANDLER WILL GO HERE 

.END START 
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ENTER 



9.4.13 .ENTER 

The .ENTER request allocates space on the specified device and creates 

a tentative entry for the named file. The channel number specified is 
associated with the file. (Note that if the program is overlaid, 
channel 15 is used by the overlay handler and should not be modified.) 

Macro Call: .ENTER .area, .chan, .dblk, .length, .count 



where : . length 



is the file size specification, 
length allocation is as follows: 



The 



file 



- 



M - 



either 1/2 the largest empty entry or 
the entire second largest empty entry, 
whichever is largest. (A maximum size 
for non-specific .ENTERs may be patched 
in the monitor.) 



a file of M blocks. M may 
maximum mentioned above. 



exceed the 



. count 



Request Format: 



RO =^ .area: 



-1 - the largest empty entry on the device. 

file number for magtape/cassette (see 
Appendix H) ; if this argument is blank, a 
value of zero is assumed. 



2 .chan 



.dblk 



. length 
•count 



The file created with an .ENTER is not a permanent file until the 
.CLOSE on that channel is given. Thus, the newly created file is not 
available to .LOOKUP and the channel may not be used by .SAVESTATUS 
requests. However, it is possible to go back and read data which has 
just been written into the file by referencing the appropriate block 
number. When the .CLOSE to the channel is given, any already existing 
permanent file of the same name on the same device is deleted and the 
new file becomes permanent. Although space is allocated to a file 
during the .ENTER operation, the actual length of the file is 
determined when .CLOSE is requested. 

Each job may have up to 256 files open on the system at any time. If 
required, all 256 may be opened for output with the .ENTER function. 
.ENTER requires that the device handler be in memory when the request 
is made. Thus, a .FETCH should normally be executed before a .ENTER 
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can be done. On return, RO contains the size of the area actually 
allocated for use. 

Notes : 

When using the length feature of .ENTER, it must be kept in mind 
that less than the largest empty space is allocated. This can have an 
important effect in transferring files between devices (particularly 
DECtape) which have a relatively small capacity. For example, to 
transfer a 20 0-block file to a DECtape on which the largest available 
empty space is 300 blocks, a length transfer will not work. Since 
the .ENTER allocates half the largest space, only 150 blocks are 
really allocated and an output error will occur during the transfer. 
If a specific length of 200 is requested, however, the transfer will 
proceed without error. 

Errors : 

Code Ex planation 

Channel is in use. 

1 In a fixed length request, no space greater 

than or equal to M was found, or in a 
non-specific request the device or the 
directory was found to be full. 



Example : 

.ENTER may be used to open a file on a specified device, and then 
write data from memory into that file as follows: 

.MCALL , ,V2.,,.REGDEF,.ENTER,.WRITW, .CLOSE , .PRINT 

.MCALL .SRESET,, EXIT, .FETCH 

..V2,. 

.REGOEF 

START! .SRESET fMAKE SURE ALU CHANNELS 

lARfc CLOSED. 

.FETCH #C0RSPC,#FPRT JFETCH DEVICE HANDLER 

BCS BA0FET I. FETCH ERROR, PROBABLY 

ULLEQAL DEVICE. 

.ENTER #AREA,#0,»FPRT I0PEN A FILE ON THE DEVICE 

ISPECIFIED, LENGTH WILL 
IGIVE 1/2 OF LARGEST EMPTY 
ISPACE NOW AVAILABLE. 

BCS BAOENT >FAILED, CHANNEL PROBABLY BUSY 

,WRJTW #AREA,#0,#BUFF,*END»BUFF/2,#0 

IWRITE DATA FROM MEMORY, THE 
>5IZE IS # OF WORDS BETWEEN 
IBUFF AND END. START AT BLOCK 0, 

BCS BA0WRT MRITE FAILURE. 

.CLOSE #0 ICL05E THE FILE 

.EXIT JANO SO TO KEYBOARD MQNJTO*. 

FPRTI .RADS0 /OK / IFILE WILL BE ON DK 

.RAD50 /FILE EXT/ INAMED FILE. EXT 
AREAI ,BLKW 10 IEMT ARGUMENT LIST 

BADFETI .PRINT KFMSG 
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• EXIT 
BADENTl .PRINT #EM8G 

.EXIT 
BADWRTt .PRINT #WMSG 

• EXIT 

FMSGI ,A3CIZ /BAD FETCH/ 
EM8GI .Aden /BAD ENTER/ 
WMSGl .ASCIZ /WRITE E**0R/ 



.EVEM 

CORSRCt .BLKW 400 REAVE 400(e) WORDS 

IFOR DEVICE HANDLER. 



BUFFI 



ENDl 



,REPT 400 »THIS IS BUFFER TO BE WRITTEN OU' 

.WORD Bit 

.ENDR 

.END START 




9.4.14 .EXIT 

The .EXIT request causes the user program to terminate. When used 
from a background job under the F/B Monitor and when used under the 
Single- Job Monitor, .EXIT causes KMON to run in the background area. 
All outstanding mark time requests are cancelled. Any I/O requests 
and completion routines pending for that job are allowed to complete. 
If part of the background job resides where KMON and USR are to be 
read, the user job is written onto system device scratch blocks. KMON 
and USR are then loaded and control goes to KMON in the background 
area. If R0=0 when the .EXIT is done, an implicit INIT command is 
executed when KMON is entered, disabling the subsequent use of 
REENTER, START, or CLOSE. 

.EXIT also resets any .CDFN and .QSET calls that were done and 
executes an .UNLOCK if a .LOCK has been done. Thus, the .CLOSE 
command from the Keyboard Monitor does not operate for programs which 
perform .CDFN requests. 

In a F/B system, an .EXIT from a completion routine acts as if a 
double CTRL C has been typed, aborting all I/O in progress before 
exiting. In general, .EXIT from a completion routine should be 
avoided. 

Macro Call: .EXIT 

Errors : 
None. 
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.FETCH 



9.4.15 .FETCH 

The .FETCH request loads device handlers into memory from the system 
device . 

Macro Call: .FETCH .coradd, .devnam 

where: .coradd is the address where the device handler is to 

be loaded. 

.devnam is the pointer to the RAD50 device name. 

The storage address for the device handler is passed on the stack,. 
When the .FETCH is complete, RO points to the first available location 
above the handler. If the handler is already in memory, RO keeps the 
same value as was initially pushed onto the stack. If the argument on 
the stack is less than 400(8), it is assumed that a handler .RELEAS is 
being done. (.RELEAS does not dismiss a handler which was LOADED from 
the KMON; an UNLOAD must be done.) After a .RELEAS, a .FETCH must be 
issued in order to use the device again. 

Several requests require a device handler to be in memory for 
successful operation. These include: 



.CLOSE 


.RE ADC 


.READ 


.LOOKUP 


.WRITC 


.WRITE 


.ENTER 


.READW 


.SPFUN 


.RENAME 


.WRITW 


.DELETE 



Since foreground jobs must have handlers resident, a .FETCH from the 
foreground will give a fatal error if the handler has not been 
previously LOADed. 



Errors : 

Code Explanation 



The device name specified does not exist, or 
there is no handler for that device in the 
system. 



Example : 

In the following example, the PR and PP handlers are fetched into 
memory in preparation for their use by a program. The program sets 
aside handler space from its free memory area. 



9-50 



Programmed Requests 



START! 



.MCALL 
..V2., 

.REGOEF 


..Ve.. f .RE60 


.FETCH 
BC9 

MOV 
.FETCH 


FREE,#PRNAME 

FERR 

R0,R2 

R2,#PPNAME 



BC* 

MOV 



FERR 
R0,FREE 



/FETCH PR HANDLER 
/FETCH ERROR 

IFETCH PP HANDIER 
IMMEDIATELY FOLLOWING 
IPR HANDLER, R0 POINTS 
/TO THE TOP OF PR 
IHANOLER ON RETURN 
IFROM THAT CALL. 
/NO PP HANDLER 
/UPDATE FREE MEMORY 
/POINTER TO POINT TO 
/NEW BOTTOM OF FREE 
IAREACTOP OF HANDLERS), 



OKI 
FERRI 



PRNAMEI 
PPNAMEl 
MSGl 

FREEl 



.PRINT 

.EXIT 

.ASCIZ 

.EVEN 

.PRINT 

.EXIT 

HALT 

.KAD50 

.RAD50 

•ASCIZ 

.EVEN 

.♦2 

.END 



*OK 

/FETCH 

#M3G 

"PR " 
ii p p ii 

"DEVICE 

START 



O.K./ 



/PRINT ERROR 

/AND EXIT 



MESSAGE 



/DEVICE NAMES 
NOT FOUND" /ERROR MESSAGE 

/POINTER TO FREE MEMORY 




9.4.16 .GTIM 

.GTIM allows user programs to access the current time of day. The 
time is returned in two words, and is given in terms of clock ticks 
past midnight. 

Macro Call: .GTIM .area, .addr 



where : . addr 

Request Format: 

RO => .area: 



is a pointer to the two words of time 
to be returned. 



21 
.addr 
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The high-order time is returned in the first word, the low-order time 
in the second word. User programs must make the conversion from clock 
ticks to hours-minutes-seconds. The basic clock frequency (50 or 60 

Hz) may be determined from the configuration word in the monitor (see 
Section 9.2.6). Under a F/B Monitor, the time of day is automatically 
reset after 24:00 when a .GTIM is done; under the Single-Job Monitor, 
it is not. The month is not automatically updated under either 
monitor. 



The clock rate is initially set to 60-cycle. Consult the RT-11 System 
Generation Manual if conversion to a 50-cycle rate is necessary. 

Errors : 

None. 

Example : 

.MCALL ,.V2,.,.REGDEF,, GTIM,, EXIT 

..V2,. 

.REGDEF 



5TARTI 

TIME! 
LXSTI 



,(TTIM *LIST,*TIME 



.EXIT 
.WORD 



,BLKW 
.END 



2 

START 



ILOW AND HI ORDER TIME 
IRETURNED WERE. 

ARGUMENTS FOR THE EMT 




9.4.17 .GTJB 

The .GTJB request passes certain job parameters back to the user 
program. 



Macro Call: 
where : 



.GTJB 
. addr 



, area , . addr 



is the address of an eight-word block into 
which the parameters are passed. The values 
returned are: 

Word 1 - Job Number. 0=Background, 
2=Fore ground 

2 - High memory limit 

3 - Low memory limit 

4 - Beginning of I/O channel 

space 
5-8 - Reserved for future use 



Request Format: 

R0 4 .area: 

January 197 6 



20 



,addr 
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In the Single-Job Monitor, the job number is always and the low 

In the F/B Monitor, the job number can either be or 2. if the job 
number equals (background job) , word 2 equals and word 4 describes 
where the I/O channel words begin. This is normally an address within 
the Resident Monitor. When a .CDFN is executed, however, the start of 
tne i/o channel area changes to the user specified area. 

Errors : 
None. 
Example : 

back* GTJB d t ° ? etermine if this Program is executing as a foreground or 

.MCALL , . V*,,,, REGDEF,.GTJB,, PRINT,, EXIT 
• « V2 , , 



STARTl 



.REGDEF 

.GTJB #UI8T,#J0BARG »R0 POINTS TO 1ST WORD ON 

JRETURN FROM CALL. 

MOV #FMSG,Ri 

TST JQBAR5 /BACKGROUND* 

BNE 1» |N0, PRINT FM8G 

MOV «BMSG,R1 

1*1 .PRINT Rl 

.EXIT 

FMSGI .ASCIZ /PROGRAM IN FOREGROUND/ 

BMSGI .ASCIZ /PROGRAM IN BACKGROUND/ 
.EVEN 

LlfTl .BUKW 2 /ARGUMENTS FOR THE EMT 

JOBARGI .BLKW 8. ,j B PARAMETERS PASSEO BACK HERE. 

.END START 



.HERR/SERR 



9.4.18 .HERR/.SERR 

.HERR and .SERR are complementary requests used to govern monitor 
behavior for serious error conditions. During program execution, 
certain error conditions may arise which cause the executing program 
«« h *i abo f ted (for example, trying to pass I/O to a device which has 
"° D f an f ler *? memory, or trying to load a device handler over the 
USR) . Normally, these errors cause program termination with one of the 
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?M- error messages. However, in certain cases it is not feasible to 
abort the program because of these errors; for example, a multi-user 
program must be able to retain control and merely abort the user who 
has generated the error. .SERR accomplishes this by inhibiting the 
monitor from aborting the job. Instead, it causes an error return to 
the offending EMT to be taken. On return from that request, the C bit 
is set and byte 52 contains a negative value indicating the error 
condition which occurred. 

.HERR turns off user error interception and allows the system to abort 
the job on fatal errors and generate an error message. (.HERR is the 
default case.) 

Macro Calls: .HERR 

.SERR 

Errors : 

Following is a list of the errors which are returned if soft error 
recovery is in effect: 

Code Explanation 

-1 Called USR from completion routine. 

-2 No device handler; this operation needs one. 

-3 Error doing directory I/O. 

-4 FETCH error. Either an I/O error 

occurred while reading the handler, or tried to 

load it over USR or RMON. 
-5 Error reading an overlay. 
-6 No more room for files in the directory. 
-7 Illegal address (F/B only) ; tried to perform a 

monitor operation outside the job partition. 
-10 Illegal channel number; number is greater 

than actual number of channels which exist. 
_H Illegal EMT; an illegal function code has 

been decoded. 

Traps to 4 and 10, and floating point exception traps are not 
inhibited. These errors have their own recovery mechanism. (See 
Section 9.4.42.) 



Example : 

This example causes a normally fatal error to generate errors back to 
the user program. The error returned is used to print an appropriate 
message. 

,MC»LL ,.Ve.,,.REG0EF,. FETCH,, ENTER,, HERR,. SERR 

.MCALL .EXIT,, PRINT 

..V2.. 

.REGDEF 

STl .SERR ;TURN ON SOFTWARE ERROR 

IRETURN3 
.FETCH #H0LR,*PTR IGET A DEVICE HANDLER 

BCS FCHERR 

.ENTER #AREA,#1,#PTR I0PEN A FIUE ON CHANNEL t 

BCS ENERR 
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.HERR 
.EXIT 



»NQW PERMIT ?M-ERR0R8, 



FCHERRl 



ENERRl 



FTLERRI 



MOVB 

BMI 

.PRINT 

• EXIT 
MOVB 
SMI 

.PRINT 
.EXIT 
NEB 
DEC 
ASL 
MOV 
.PRINT 

• EXIT 



M38,R0 
FTUERR 
• FM3G 

M52,R0 

FTLERR 
#EM8G 

R0 
R0 

Re 

TBL(R0),R0 



MAS IT FATAL 

IYES 

|NO... NO DEVICE BY THAT NAME 



ITHIS WILL TURN POSITIVE 

JADJUST BY ONE 

IMAKE IT AN INOEX 

JPUT MESSAGE ADDRESS INTO R0 

JANO PRINT IT, 



TBUI 



Mil 

M2I 

M3I 

M4J 

MSI 

Mil 

M7I 

M10I 

Mill 

FMS6I 

EMSGI 

HOLRI 

PTRl 



AREAI 



Ml 

M2 

M3 

M« 

M5 

Mb 

M? 

MIB 

MU 



.ASCIZ 
.A8CIZ 
.AICU 

.ASCIZ 
.ASCIZ 
.ASCIZ 
•ASCIZ 

.ASCIZ 
.ASCIZ 

.EVEN 

.BUKW 

.RADS0 

.RAO50 

.RAD50 

,BLKU 

.END 



ICAN'T OCCUR IN THIS PROGRAM 
INO DEVICE HANDLER IN MEMORY 
•DIRECTORY I/O ERROR 
IFETCH ERROR 

IMPOSSIBLE FOR THIS PROGRAM 
INO ROOM IN DIRECTORY 
IILLEGAL ADDRESS (F/B) 
•ILLEGAL CHANNEL 
IILLEGAL EMT 

ICAN'T OCCUR IN THIS PROGRAM 
/NO DEVICE HANDLER/ 
"DIRECTORY I/O ERROR" 
/ERROR OOING FETCH/ 

INOT APPLICABLE TO THIS PROGRAM 
/NO ROOM IN OIRECTORY/ 
/ADDRESS CHECK ERROR/ 

'ILLEGAL CHANNEL/ 
/II LFG«L EMT/ 
/FITCH FAILED/ 
/ENTER FAILED/ 



300 
/DT«/ 
/EXAMPL/ 
/HAC/ 

4 
ST 



ILEAVE 300 (OCTAL) FOR HANDLER 
/DEVICE ANO FILE NAME, 



IEMT AREA 



.HRESET 



9.4.19 .HRESET 

This request performs the same function as .SRESET, after stopping all 
I/O transfers in progress for that job. (.HRESET is not used to clear 
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a hard-error condition.) Note that in the single-job environment, a 
hardware RESET instruction is used to terminate I/O, while in a F/B 
environment, only the I/O associated with the job which issued the 
.HRESET is affected. All other transfers continue. 

Macro call: .HRESET 

Errors : 

None. 

Example : 

See the example for .SRESET (Section 9.4.40) for format. 



.LOCK/.UNLOCK 



9.4.20 .LOCK/.UNLOCK 



.LOCK 

The .LOCK request is used to "lock" the USR in memory for a series of 
operations. If all the conditions which cause swapping are satisfied, 
the user program is written into scratch blocks and the USR is loaded. 
Otherwise, the USR which is in memory is used, and no swapping occurs. 
The USR is not released until an .UNLOCK request is given. (Note that 
in a F/B System, calling the CSI may also perform an implicit 
.UNLOCK.) A program which has many USR requests to make can .LOCK the 
USR in memory, make all the requests, and then .UNLOCK the USR; no 
time is spent doing unnecessary swapping. 

In a F/B environment, a .LOCK inhibits the other job from using the 
USR. Thus, the USR should be locked only as long as necessary. 

Macro Call: .LOCK 

Note that the .LOCK request reduces time spent in file handling by 
eliminating the swapping of the USR in and out of memory. If the USR 
is currently resident, .LOCK is ignored. After a .LOCK has been 
executed, an .UNLOCK request must be executed to release the USR from 
memory. The .LOCK/.UNLOCK requests are complimentary and must be 
matched. That is, if three .LOCK requests are issued, at least three 
.UNLOCKS must be done, otherwise the USR will not be released. More 
.UNLOCKS than .LOCKs may occur without error. 



Notes : 



1. It is vital that the .LOCK call not come from within the area 
into which the USR will be swapped. If this should occur, 
the return from the USR request would not be to the user 
program, but to the USR itself, since the LOCK function 
inhibits the user program from being re-read. 
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2. 



3. 



Once a .LOCK has been performed, it is not advisable for the 
program to destroy the area the USR is in, even though no 
further use of the USR is required. This causes 
unpredictable results when an .UNLOCK is done. 

If a foreground job perforins a .LOCK request while the 
background job owns the USR, foreground execution is 
suspended until the USR is available. Thus, in this case, it 
is possible for the background to lock out the foreground (see 
the .TWAIT request) . 



Errors : 



None. 

Example : 

See the example following .UNLOCK. 
.UNLOCK 

The .UNLOCK request releases the User Service Routine from memory if 

it was placed there with a .LOCK request. If the .LOCK required a 

swap, the .UNLOCK loads the user program back into memory. If the USR 
does not require swapping, the .UNLOCK acts as a no-op. 

Macro Call: .UNLOCK 



Notes t 



1. 



2. 



It is important that at least as many .UNLOCKS are given as 
.LOCKs. If more .LOCK requests were done, the USR remains 
locked in memory, it is not harmful to give more UNLOCKS 
than are required; those that are extra are ignored. 

The .LOCK/. UNLOCK pairs should be used only when absolutely 
necessary when running two jobs in the F/B system. When a 
job .LOCKs the USR, the other job cannot get at it until it 
is .UNLOCKed. Thus, the USR should not be .LOCKed 
unnecessarily, as this may degrade performance in some cases. 



3. 



Errors : 



None. 



Example : 



In a F/B System, calling the CSI with input coming 
console terminal performs an implicit .UNLOCK. 



from the 



This example shows the usage of .LOCK, .UNLOCK, and their interaction 
with the system. 



.MCALL 
, MCALL 
..V2.. 

.REGDEF 



,.V2..,. REGDEF,, LOCK,, UNLOCK , .LOOKUP 
.8ETTQP, .PRINT, .EXIT 



STARTl 



SYSPTR«54 



.SETTOP M8YSPTR 
MOV R0,TOP 
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y .LOCK >BRING USR INTO MEMORY 

.LOOKUP #LI8T,#0,#FILEl HOOKUP * FILE ON CHANNEL 

8CC IS ION ERROR, PRINT A 

2SI .PRINT #LM8G ^MESSAGE AND EXIT 

.EXIT 

1S1 MOV #LIST,R0 

INC (R0) >DO LOOKUP ON CHANNEL 1 

MOV #FILE2,2(R0) INEW POINTER 
.LOOKUP ; ALL ARCS ARE FILLED IN 

bcs as 

.UNLOCK iNOIn RELEASE USR 

.EXIT 

LISTI ,BLKW 3 ISPACE FOR ARGUMENTS 

FILEU .RAD50 /OK / 

.RAD50 /FILEX MAC/ 

FILE2I .RAO50 /OK / 

.RAD50 /FILE2 MAC/ 

TOPI ,WORO 

LMSGl .ASCIZ /LOOKUP ERROR/ 

.EVEN 

,CNO START 

In the above example, .SETTOP tries to obtain as much memory as it 
can. Most likely this will/ in a background job, make the USR 
non-resident (i.e., unless a SET USR NOSWAP command is done at the 
keyboard) . Thus, if the USR were non-resident, swapping must take 
place for each .LOOKUP given. Using the .LOCK, the USR is brought 
into memory and remains there until the .UNLOCK is given. 

The second .LOOKUP makes use of the fact that the arguments have 
already been set up at LIST. Thus, it is possible to increment the 
channel number, put in a new file pointer and then give a simple 
.LOOKUP, which does not cause any arguments to be moved into LIST. 



.LOOKUP 



9.4.21 .LOOKUP 

The .LOOKUP request associates a specified channel with a device 
and/or file, for the purpose of performing I/O operations. The 
channel used is then "busy" until one of the following requests is 
executed: 

.CLOSE 

.SAVESTATUS 

.SRESET 

.HRESET 

.PURGE 

.CSIGEN (if channel is in range 0-10 octal) 

Note that if the program is overlaid, channel 15 is used by the 
overlay handler and should not be modified. 
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Macro Call: 
where : 



.LOOKUP .area, .chan, .dblk, .count 

.count is an argument which can optionally be used 
for the cassette and magtape handlers. Refer 
to Appendix H for details of this parameter. 
If .count is blank, a value of zero is 
assumed. 



Request Format: 


. area : 






RO * 


1 


.chan 




.dblk 




. count 



If the first word of the file name in .dblk is zero and the device is 
a file-structured device, absolute block of the device is designated 
as the beginning of the "file". This technique allows I/O to any 
physical block on the device. If a file name is specified for a 
device which is not file-structured (i.e. PR:FILE.BXT) , the name is 
ignored. 

The handler for the selected device must be in memory for a .LOOKUP. 

On return from the .LOOKUP, RO contains the length (number of blocks) 
of the file just looked up. If the length returned is 0, a nonfile- 
structured .LOOKUP was done to the device. 



Errors : 

Code 


1 



Explanation 

Channel already open. 

File indicated was not found on the device. 



Example : 

In the following example, the file "DATA. 001" on device DT3 is opened 
for input on channel 7. 

.MCALL ,,V2,,,,REGDEF,, FITCH,, LOOKUP,. PRINT,, EXIT 

..V2.. 

.REGDEF 



STARTl 
ERR*0«52 



NFOl 

CAMS6I 



.FETCH #H8PACE,#DT3N 

BCS PERR 

.LOOKUP «LIST,#7,#DT3N 

BCC LDONE 

TSTB MERRWD 

BNE NFD 

.PRINT iCAMSG 

.EXIT 

.PRINT #NFMSG 

.EXIT 

,A$CIZ /CHANNEL ACTIVE/ 
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I6ET DEVICE HANDLER 
I0T3 13 NOT AVAILABLE 
IL00KUP THE FILE 
ION CHANNEL T 
•FILE HAS FOUND 
IERR0R, WHAT'S HRQNGT 
IFILE NOT FOUND 
IPRINT 'CHANNEL ACTIVE* 

•FILE NOT FOUND 
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NFMSGl 


.A8CIZ 


QTMSGl 


.ASCIZ 




.EVEN 


FERRl 


.PRINT 




.EXIT 



LOONEI 



LXSTI 

0T3NI 



HSPACEl 



/ULE NOT FOUND/ /ERROR MESSAGES 
/OTS NOT AVAILABLE/ 



•DTMSG 



• EXIT 

.8LKW 5 

.RAO50 "OTS" 

.RAOS0 "OAT" 

.RAO50 h a n 

.RAD50 «00i« 



.K.+400 

,EN0 START 



/PROGRAM CAN NOW 
II89UE READS AND 
/WRITES TO FILE 
/DATA. 00} VIA 
(CHANNEL ? 



IOEVICE 

/FILENAME 
/FILENAME 
/EXTENSION 



/RESERVED SPACE FOR DT 
/HANDLER 




9.4.22 .MRKT 

The .MRKT request schedules a completion routine to be entered after a 
specified time interval (clock ticks past midnight) has elapsed. 



Macro Call: 
where : 



Request Format: 



.MRKT .area, .time, .crtn, .id 

.time is the pointer to the two words containing 
the time interval (high-order first; 
low-order second) . 

.id is a number assigned by the user to identify 
the particular request to the completion 
routine and to any cancel mark time requests. 

The number must not be within the range of 
codes from 177400-177777; these are reserved 
for system use. The number need not be 
unique (i.e., several .MRKT requests may 
specify the same .id.) On entry to the 
completion routine, the .id number is in R0. 



R0 4 .area: 



22 



.time 



,crtn 



nd 
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.MRKT requests require a queue element taken from the same list as the 
I/O queue elements. The element is in use until either the completion 
routine is entered or a cancel mark time request is issued. The user 
should allocate enough queue elements to handle at least as many mark 
time requests as he expects to have pending simultaneously. 

Errors : 

Code Explanation 

No queue element was available. 

Example : 

In this example, a mark time is set up to time out an I/O transfer. 
If the mark time expires before the transfer is done, a message is 
printed. If the I/O transfer completes before the mark time, the mark 
time is cancelled. (Note that the example assumes the I/O channel is 
already open.) 

..V2,,,,REG0EF,, READ,. WAIT,. MRKT,, CMKT 
.OSET,, PRINT,, EXIT,. LOOKUP 



STl .LOOKUP »AREA,#0,#FILE (OPEN A FILE 

LKERR (PILE NOT FOUNO 

«AREA,»(8P) |EMT LIST TO STACK 

#flUEUE,#5 (ALLOCATE 3 MORE ELEMENTS 

CSP},*INTRVL,#MRTN,#i (SET TIMER GOING 

NOMRKT (FAILED. 

**DL»T (START I/O TRANSFER 

RDERR 

*B (AND WAIT A WHILE, 

C»P),#» (SEE IF MARK TIME IS 

(DONE, 
8CS NOTDUN IFAILED, THAT MEANS THAT 

ITHE MARK TIME ALREADY 

(EXPIRED. 

.EXIT 



.MCALL 


.MCALL 


..vs.. 


.REGDEF 


.LOOKUP 


ACS 


MOV 


,GSET 


,MRKT 


BCS 


.READ 


BCS 


.WAIT 


,CMKT 



MRTNI .CMKT (BP),#t IQK, KILL THE TIMER. 

, PRINT #FAIL (DON'T WORRY ABOUT AN 

(ERROR MERE, 

RTS PC 

LKERRl .PRINT »LM 

.EXIT 

ROERRl .PRINT #RDM5G 

.EXIT 

NOTOUNl .PRINT #FAIL 

.EXIT 

NOMRKTl .PRINT #N00 

.em 

NOQI .ASCIZ /NO QUEUE ELEMENTS AVAILABLE/ 

FAILI .ASCIZ /MARK TIME COMPLETED BEFORE TRANSFER/ 

LMI .ASCIZ /LOOKUP ERROR/ 

ROMSGI .ASCIZ /READ ERROR/ 

.EVEN 

INTRVLl .WORD 0,13. MLLOW 13 CLOCK 



(TICKS FOR TRANSFER, 
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QUEUEl 


,BLKW 


5*7 


AREA! 


,BLKW 


S 


FILE! 


.RAD5B 


/DK FILE 


RDLSTl 


.BYTE 







.BYTE 


10 


ILOCKt 


.WORD 







.WORD 


BUFF 




.WORD 


25b, 




.WORD 


X 


BUFFI 


.BUKW 


2S6, 



T3T/ 



|AREA FOR QUEUE ELEMENTS 
|A FEW WORDS FOR EMT LIST 

ICHANNEL e 
|A READ 
IBLOCK « 
IBUFFER 
fl BLOCK 



,|ND 



ST 



.MWAIT 



9.4.23 .MWAIT 

This request is similar to the .WAIT request. .MWAIT, however, 
suspends execution until all messages sent by the other job have been 
transmitted or received. It provides a means for ensuring that a 
required message has been processed. It should be used primarily in 
conjunction with the .RCVD or .SDAT modes of message handling, where 
no action is taken when a message is completed. 

Macro Call: .MWAIT 

Errors : 

None. 

Example : 

This program requests a message, does some intermediate processing, 
and then waits until the message is actually sent. 



.MCALL 
..VS.. 

.RIGOEF 

WQRD3»233, 
START! 

.RCVD 



MOV 

, MWAIT 
CMPB 
BNt 

,|XIT 
BADMSGI .PRINT 
.EXIT 



,.V2 I6DEF,. MWAIT,. RCVD,, EXIT,. PRINT 



«AREA,#R6UFF,#W0RDS »GET MESSAGE. 

INTERMEDIATE PROCESS 



#RBUFF*2,R3 

(RS)*,#'A 

BAOMSG 



*MSG 



IMAKE SURE WE HAVE IT, 
IFIR8T CHARACTER AN A? 
|N0, INVALID MESSAGE 
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N8GI 


, ASCIZ 


/BAD MESSAGE/ 


AREAI 


.BLKW 


10 


RBUFFl 


,BLKW 
.EVEN 


256, 




• END 


START 



.PRINT 



9.4.24 .PRINT 

The .PRINT request causes output to be printed at the console 
terminal. When a foreground job is running and a change occurs 
in the job producing output, a B> or F> appears. Any text following 
the message has been printed by the job indicated (foreground or 
background) until another B> or F> is printed. The string to be 
printed may be terminated with either a null (0) byte or a 200 byte. 
If the null (ASCIZ) format is used, the output is automatically 
followed by a <CR><LF>. If a 200 byte terminates the string, no 
<CR><LF> is generated. 

Macro Call: .PRINT .addr 

where: .addr is the address of the string to be printed. 

Control returns to the user program after all characters have been 
placed in the output buffer. 

The foreground job issues a message immediately using .PRINT no matter 
what the state of the background job. Thus, for urgent messages, 
.PRINT should be used (rather than .TTYIN or .TTYOUT) . 

Errors : 

None. 

Example: 

.HCALL ,.V2.,,,REGDEF,, PRINT,. EXIT 
..V2.. 



,RECDEP 



STARTI 



.PRINT «82 

.PRINT #S1 

.EXIT 

St I , ASCIZ /THIS WILL HAVE CR-LF FOLLOWING/ 

82: .ASCII /THIS WILL NOT HAVE CR-LF/ 

.BYTE 2(90 

.EVEN 

.END START 
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.PROTECT 



9.4.25 .PROTECT 

The .PROTECT request is used by a job to obtain exclusive control of a 
vector (two words) in the region 0-476. If it is successful, it 
indicates that the locations are not currently in use by another job 
or by the monitor, in which case the job may place an interrupt, 
address and priority into the protected locations and begin using the 
associated device. 



Macro Call: 
where : 



.PROTECT .area, .addr 



.addr 



is the address of the word pair to be 
protected. .addr must be a multiple of! 
four, and must be less than 476 (octal) ., 
The two words at .addr and .addr+2 will be 
protected. 



Request Format: 



R0 4 .area: 



31 



.addr 



Errors : 

Code 



1 



Explanation 

Protect failure; locations already in use. 
Address greater than 476 or not a multiple of 4. 



Example : 

This example shows the use of .PROTECT to gain control of the UDC11 
vectors . 



3TI 



.MCALL ,,Va,.,,REeDEF,, PROTECT,. PRINT,. EXIT 

..VZ.. 

.RE60EF 

MOV #AREA,-(SP) 

MOV #|3«,R5 IU0C VECTOR ADDRESS 

.PROTECT (8P),RS IPRQTECT 834,23b 

SCI ERR IY0U CAN'T 

MOV #UDCINT,CR5)+ UNITIALIZE THE VECTORS, 

MOV #3«0,(R5) |AT LEVEL 7 





.EXIT 


ERRI 


.PRINT 




.EXIT 


AREAI 


.SLKH 


NOVECI 


.AJCIi! 



iNOVEC 



/VECTORS ALREADY IN USE/ 
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• EVEN 



UOCINTI 



.PURGE 



9.4.26 .PURGE 

The .PURGE request is used to de-activate a channel without performing 
a .HRESET, .SRESET, .SAVESTATUS, or .CLOSE request. It merely frees a 
channel without taking any other action. If a tentative file has been 
.ENTERed on the channel, it will be discarded. Purging an inactive 
channel acts as a no-op. 

Macro Call: .PURGE . chan 

Errors: 

None. 

Example : 

The following code is used to make certain that channels 0-7 are free: 

.MCALL ,.V2,., ,REGDEF,,PUR5I,.EXIT 
..VS., 

•REGOEF 



STARTl 



111 



CUR 

.PURGE 

INC 

CMP 
BIO 

.EXIT 
.END 



Rl 

Rl 

Rt 

Rl,#8, 

IS 



START 



fSTART WITH CHANNEL 
tPURGE A CHANNEL 
JBUMP TO NEXT CHANNEL 
IIS IT AT CHANNEL 8 YET? 
|N0 f KEEP GOING 




9.4.27 .QSET 

All RT-11 I/O transfers are done through a centralized queue 
management system. If I/O traffic is very heavy and not enough queue 
elements are available, the program issuing the I/O requests may be 
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suspended until a queue element becomes available. In a F/B system, 
the other job runs while the first program waits for the element. 

The ,QSET request is used to make the RT-11 I/O queue larger (i.e.,, 
add available entries to the queue) . A general rule to follow is that 
each program should contain one more queue element than the total 
number of I/O requests which will be active simultaneously. Timing 
requests such as .TWAIT and .MRKT also cause elements to be used and 
must be considered when allocating queue elements for a program. Note 
that if synchronous I/O is done (i.e. .READW/.WRITW, etc.) and no 
timing requests are done, no additional queue elements need be 
allocated. 

Macro Call: .QSET .addr, .qleng 

where: .addr is the address at which the new elements are 

to start. 

.qleng is the number of entries to be added. Each 
queue entry is seven words long; hence the 
space set aside for the queue should be 
.qleng * 7 words. 

Each time .QSET is called, a contiguous area of memory is divided into 
seven-word segments and is added to the queue for that job. .QSET may 
be called as many times as required. The queue set up by multiple 
.QSET requests is a linked list. Thus, .QSET need not be called with 
strictly contiguous arguments. The space used for the new elements is 
allocated from the user's program space. Thus, care must be taken so 
that the program in no way alters the elements once they are set up. 
The .SRESET and .HRESET requests discard all user-defined queue 
elements; therefore any .QSETs must be reissued. 

Care should also be taken to allocate enough memory for the queue. 
The elements in the queue are altered by the monitor; if enough space 
is not allocated, destructive references will occur in an unexpected 
area of memory. 



Errors : 






None. 






Example : 


.MCALL 
,.V«.. 

.REGDEF 


..V2.. 


STARTl 


.QSET 


#8ti#5 




.QSET 


•03, #3 




.EXIT 




on 

031 


.BLKW 
.BLKW 


7*5. 
7*3. 



. ,V2.,,.RER0FF,.nSFTi.EXlT 



(ADO 5 ELEMENTS TO THE QUEUE 
fSTARTINS AT Ql 
IAND 3 MORE AT Q3. 



IFXRST QUEUE AREA (35 DECIMAL W0RD»> 
ISECONO QUEUE AREA C2V DECIMAL WORDS) 



.END START 
Note that Ql and Q3 need not have been contiguous. 
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RCTRLO 



9.4.28 .RCTRLO 

The .RCTRLO request ensures that the console terminal Is able to 
print. Since CTRL O (to) struck while output is directed to the 
console terminal inhibits the output from printing until either 
another to is struck or until the program resets the *0 switch, a 
program that has a message which must appear at the console can 
override to struck at the keyboard. 

Macro Call: .RCTRLO 

Errors : 

None. 

Example : 

In this example, the user program first calls the CSI in general mode, 
then processes the command. When finished, it returns to the CSI for 
another command line. To make certain that the prompting "*" typed by 
the CSI is not inhibited by a CTRL in effect from the last 
operation, terminal output is re-enabled via a .RCTRLO command prior 
to the CSI call. 

.MCALL ,.V2,,, .REGDEF, .RCTRLO, .CSI SEN, .EXIT 
.KE6DEF 

START/ .RCTRLO /MAKE SURE TT OUTPUT IS 

/ENABLED 
.CIIBEN #OSPACE,#OEXT,#0 /CALL CSI-IT WILL TYPE 

/ " * •' 

/PROCESS COMMAND 

JMP START IGET NEXT COMMANO 

OiXTl /NO DEFAULT EXTENSIONS 



id 

9 
DSPACEI ,«,*400 /HANDLER SPACE 

.END START 
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.RCVD/,RCVDC/.RCVDW 



9.4.29 .RCVD/.RCVDC/.RCVDW (F/B Only) 

There are three forms of the receive data request; these are used in 
conjunction with the .SDAT (Send Data) requests to allow a general 
data/message transfer system. .RCVD requests can be thought of as 
.READ requests, where data transfer is not from a peripheral device 

but from the other job in the system. Additional queue elements should 
be allocated for buffered I/O operations in .RCVD and .RCVDC requests 

(see .QSET) . 



.RCVD 

This request is used to receive data and continue execution. The 
request is posted and the issuing job continues execution. At some 
point when the job needs to have the transmitted message, an .MWAIT 
should be executed. This causes the job to be suspended until the 
message has been received. 



Macro Call: 

where : 



.RCVD .area, .buff, .went 
.buff 



•went 



is the address of the buffer 
message is to be sent. 



to which the 



is the number of words to be transferred. 



Request Format: 



RO 4 .area: 



26 



(unused) 
.bu"ff" 



.went 
I 



Word (the first word) of the message buffer will contain the number 
of words transmitted whenever the .RCVD is complete. Thus, the space 
allocated for the message should always be at least one word larger 
than the actual message size expected. 

The word count is a variable number, and as such, the .SDAT/. RCVD 

combination can be used to transmit a few words or entire buffers. 

The .RCVD operation is only complete when a .SDAT is issued from the 
other job. 

Programs using .RCVD/. SDAT must be carefully designed to either always 
transmit/receive data in a fixed format or have the capability of 
handling variable formats. The messages are all processed in FIFO 
(first in- first out) order. Thus, the receiver must be certain it is 
receiving the message it actually wants. 
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Errors : 

Code 



Explanation 

No other job exists in the system. 



Example : 

An example follows the .RCVDW section. 



.RCVDC 

The .RCVDC request receives data and enters a completion routine when 
the message is received. The .RCVDC request is posted and program 
execution stays with the issuing job. When the other job sends a 
message, the completion routine specified will be entered. 

Macro Call; .RCVDC .area, .buff, .went, .crtn 



where: .buff 

• went 
.crtn 



is the address of the buffer to which the 
message is to be sent. 

is the number of words to be transmitted. 

is the completion routine to be entered (see 
Section 9.2.8) . 



As in the others, word of the buffer contains the number of words 
transmitted when the transfer is complete. 

Request Format: 

RO =► area: 



26 



(unused) 



.buff 



• went 



.crtn 



Errors : 

Code Explanation 

No other job exists in the system. 
Example : 
An example follows the .RCVDW section. 



.RCVDW 

.RCVDW is used to receive data and wait. A message request is posted 
and the job issuing the request is suspended until the other job sends 
a message to the issuing job. When the issuing job runs again, the 
message has been received, and word of the buffer indicates the 
number of words which were transmitted. 
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Macro Call: 
where : 



. RCVDW 
.buff 



.area, .buff, .went 



.went 
Request Format: 

RO 4 .area: 



to which the 
is the number of words to be transmitted. 



is the address of the buffer 
message is to be sent. 



Errors : 



Code 



26 




(unused) 




.buff 




.went 









Explanation 



No other job exists in the system. 



Example : 



In this example, the running job receives a message from the second 
job and interprets it as the device and filename of a file to be 
opened and used. In this case, the message was in RAD50 format, and 
the receiving program did not use the transmitted length for any 
purpose . 

.MCAU ,.V8,,,,REGQEF # ,RC VOW,, PURGE,. LOOKUP,, EXIT,, PRINT 
» i V2» , 



STARTI 



.REGQEF 



MOV #AREA,R5 

.RCVOW «5,#FILE,#« 

BC8 MERR 

.PURGE #0 

.LOOKUP R5,#0,#FILE*2 

8C» LKERR 

.EXIT 



AREAI 


.*LKH 


10 


FILEI 


,8LKW 


t 




iBLKW 


4 


MERRI 


, PRINT 
.EXIT 


#MMS6 


LKERRl 


.PRINT 
tEXIT 


#LKMSG 


MMSGl 


.A8C12 


/MESSAGE ERROR/ 


LKHSGI 


.ASCIZ 

.EVEN 


/LOOKUP ERROR/ 




.END 


START 



|R5"£MT ARC, AREA 
^REQUEST MESSAGE ANO WAIT 
IAN ERROR? 
/CLEAR CHANNEL 
ILOOKUP INOICATEO FILE 
IERH0R 



ILEAVE SPACE FOR SAFETY 
FACTUAL WORD COUNT IS MERE 
JUEVlFILE.EXT ARE HERE 



The issuing job is suspended until the indicated data is transmitted. 
Either of the other modes could have also been used to receive the 
message. 
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.READ/READC/READW 



9.4.30 .READ/.READC/.READW 

RT-11 provides three modes of I/O: .READ/. WRITE, .READC/.WRITC, and 
.READW/.WRITW. Section 9.4.47 explains the output operations. The 
input operations are described next. 



Note that in the case of .READ and .READC, additional queue 
should be allocated for buffered I/O operations (see .QSET) . 



elements 



.READ 



The .READ request transfers a specified number of words from the 
specified channel to memory. Control returns to the user program 
immediately after the .READ is initiated. No special action is taken 
when the transfer is completed. 

Macro Call: .READ .area, .chan, .buff, .went, .blk 



where: .buff 



is the address of the buffer to receive the 
data read. 



.went 



.blk 



Request Format: 

R0 4 .area: 



is the number of words to be read. 

is the block number to be read relative to 
the start of the file, not block of the 
device. The monitor translates the block 
supplied into an absolute device block 
number. The user program normally updates 
.blk before it is used again. If .blk-0, TT: 
gives " prompt and LP: gives form feed. 
(This is true for all .READ and .WRITE 
requests . ) 



10 



.chan 



.blk 



.buff 



.went 



- 



When the user program needs to access the data read on the specified 
channel, a .WAIT request should be issued. This ensures that the data 
has been read completely. If an error occurred during the transfer, 
the .WAIT request indicates the error. 
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Errors : 

Code 





1 
2 



Explanation 

Attempt to read past end-of-file 
Hard error occurred on channel 
Channel is not open 



Example : 

Refer to the . WRITE/. WRITC/.WRITW examples, 



.READC 

The .READC request transfers a specified number of words from the 
indicated channel to memory. Control returns to the user program 
immediately after the .READC is initiated. Execution of the user 
program continues until the .READC is complete, then control passes 
to the routine specified in the request. When an RTS PC is executed 
in the completion routine, control returns to the user program. 

Macro Call: .READC .area, .chan, .buff, .went, .crtn, .blk 

where: .buff is the address of the buffer to receive the 

data read. 

.went is the number of words to be read. 

.crtn is the address of the user's completion 

routine (refer to Section 9.2.8). 

.blk is the block number relative to the start of 
the file, not block of the device. The 
monitor translates the block supplied into an 
absolute device block number. The user 
program normally updates .blk before it is 
used again. 

Request Format: 

RO =^ .area: 



10 .chan 



.blk 



.buff 



.wen t _^ 

address of completion routine 



when entering a .READC completion function the following are true: 

1. RO contains the channel status word for the operation. If 
bit of RO is set, a hardware error occurred during the 
transfer. The data may not be reliable. 

2. Rl contains the octal channel number of the operation. This 
is useful when the same completion function is to be used for 
several different transfers. 
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Errors t 

Code 



1 
2 



Explanation 

Attempt to read past end-of-file 
Hard error occurred on channel 
Channel Is not open 



Example : 

Refer to the . WRITE/. WRITC/.WRITW examples. 



.READW 

Tne .READW request transfers a specified number of words from the 
indicated channel to memory. Control returns to the user program when 

the .READW is complete or if an error is detected. 

Macro Call: .READW .area, .chan, .buff, .went, .blk 



where: .buff 



.went 



.blk 



is the address of the buffer to receive the 
data read. 

is the number of words to be read. The 
number must be positive. 

is the block number relative to the start of 
the file, not block of the device. The 
monitor translates the block supplied into an 
absolute device block number. The user 
program normally updates .blk before it is 
used again. 



Request Format: 



RO 4 .area: 



10 .chan 



.blk 



.buff 
.went 



Oil return from this call, the C bit set indicates an error has 
occurred. If no error occurred, the data is in memory at the 
specified address. In an F/B system, the other job can be run while 
the issuing job is waiting for the I/O to complete. 



Note : 

Upon return from any READ prog 
information if the read is 
example, magtape) . If the read 
DECtape) RO will contain the ac 
(.READ or .RE ADC) or have been 
the requested word count if an 
of-file, but a partial transfer 
transfer, the C bit is set and 



rammed request, RO will contain no 
from a sequential-access device (for 
is from a random-access device (disk, 
tual number of words that will be read 
read (.READW). This will be less than 
attempt is made to read past the end- 
is possible. In the case of a partial 
error code is returned. Therefore, a 
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program should always use the returned would count as the number of 
words available. For example, suppose a file is 5 blocks long (i.e. , 
it has block numbers to 4) and a request is issued to read 512 words, 
starting at block 4. The request is shortened to 256 words; no error 
is indicated. Also note that since the request will be shortened to 
an exact number of blocks, a request for 256 words will either succeed 
or fail, but cannot be shortened. 





1 
2 



Explanation 

Attempt to read past end-of-file 
Hard error occurred on channel 
Channel is not open 



Example i 

Refer to the . WRITE/. WRITC/.WRITW examples. 



.RELEAS 



9.4.31 .RELEAS 

The .RELEAS request removes the handler for the specified device from 
memory. The .RELEAS is ignored if the handler is: 

1. Part of RMON (i.e., the system device), 

2. Not currently resident, or 

3. Resident because of a LOAD command to the Keyboard Monitor, 

.RELEAS from the foreground is always ignored, since the foreground 
can only use handlers which have been LOADed. 

Macro Call i .RELEAS .devname 

where: .devname is the pointer to the .RAD50 device name. 



Errors : 

Code 



Explanation 

Handler name was illegal. 
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Example : 

In the following example, the DECtape handler (DT) is loaded into 
memory, used, then released. If the system device is DECtape, the 
handler is already resident, and .FETCH will return HSPACE in RO. 

.MCALL , ,V2.., ,REG0EF,,FETCH # ,RELEA3,,£XJT 

..V2,. 

.RE6DEF 

STARTl .P6TCH #HSPACE,«OTNAME ILOAD DT HANDLER 



BC8 FERR 

I USE HANDLER 

.RELEAS IHOTNAME 

BR START 
FERRl HALT 
DTNAMEl .RAD50 /OT / 
HSPACEI 



INOT AVAILABLE 



IHARK DT NO LONGER IN 
•MEMORY, 

IDT NOT AVAILABLE 
INAME FOR DT HANDLER 
•BEGINNING OF HANDLER 
IAREA 



.END 



START 



.RENAME 



9.4.32 .RENAME 

The .RENAME request causes an immediate change of name of the file 
specified. An error occurs if the channel specified is already 
open . 

Macro Call > .RENAME .area, .chan, .dblk 

Request Format: 

RO 4 .area: 



.chan 



.dblk 



The .dblk argument consists of two consecutive . RAD50 device and file 
specifications. For example: 



DBLK: 



.RENAME 
BCS 



RAD50 
RAD50 
RAD50 
RAD50 
RAD50 
RAD50 



#AREA,#7,#DBLK 
RNMERR 



/DTV 

/OLDFIL/ 

/MAC/ 

/DT3/ 

/NEWFIL/ 

/MAC/ 



I USE CHANNEL 7 
;NOT FOUND 
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The first string represents the file to be renamed and the device it 
is found on. The second represents the new file name. If a file with 
the same name as the new file name specified already exists on the 
indicated device, it is deleted. The second occurrence of the device 
name DT3 is necessary for proper operation, and should not be omitted. 
The specified channel is left inactive when the .RENAME is complete. 
.RENAME requires that the handler to be used be resident at the time 
the .RENAME request is made. If it is not, a monitor error occurs. 
Note that .RENAME is legal only on files which are on disk or DECtape. 
(.RENAMES to other devices are ignored.) 



Errors : 

Code 



Explanation 




1 



Channel open 
File not found 



Example : 

In the following example, the file 
DATA. 001: 



DATA.TMP on DTO is renamed to 



.MCAU .,V2,.,,REGDEF,. FETCH,, PRINT 

.MCALl .EXIT,, RENAME 

..V2.. 

.RIGDEF 



STARTl .FETCH iHBPACEi #NAMBt.K >GET HANDLER 
BC» FERR I30ME ERROR 

.RENAME #AREA,»0,»NAMBLK >DQ THE RENAME 



BCI 

.EXIT 
FERRI .PRINT 

.EXIT 
RNMERRI .PRINT 

.EXIT 



AREA! 

NAMBLKI 

FMSGI 
RNMSGl 

HSPACEl, 



.BLKW 

.RAO50 

.RAO50 

.ASCIZ 

.ASCIZ 

.EVEN 



RNMIRR 

#FM8G 

•RNMSG 



/DT0OATA 
/DT0OATA 
/FETCH?/ 
/RENAME?/ 



IERR0R 



TMP/ 
0(31/ 



»R00M FOR ARGS. 
»OL0 NAME 
INEW NAME 
IERR0R MESSAGES 



.END 



START 
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REOPEN 



9.4.33 



, REOPEN 



The .REOPEN request reassociates the specified channel with a file on 
which a .SAVESTATUS was performed. The .SAVESTATUS/. REOPEN 
combination is useful when a large number of files must be operated on 
at one time. As many files as are needed can be opened with .LOOKUP, 
and their status preserved with .SAVESTATUS. When data is required 
from a file, a .REOPEN enables the program to read from the file. The 
.REOPEN need not be done on the same channel as the original .LOOKUP 
and .SAVESTATUS. 



Macro Call: 
where : 



.REOPEN .area, ,chan, .cblk 

.cblk is the address of the five-word block where 
the channel status information was stored. 



Request Format: 

RO 4 .area: 



.chan 



.cblk 




Explanation 

The specified channel is in use. The .REOPEN has not 
been done. 



Example : 

Refer to the example following the description of .SAVESTATUS. 



9.4.34 .SAVESTATUS 



. SAVESTATUS 



The .SAVESTATUS request stores five words of channel status I 
information into a user-specified area of memory. These words contain 
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all the information RT-11 requires to completely define a file. When 
a .SAVESTATUS is done, the data words are placed in memory, and the 
specified channel is again available for use. When the saved channel 
data is required, the .REOPEN request is used. 

.SAVESTATUS can only be used if a file has been opened with .LOOKUP, 

If .ENTER was used, .SAVESTATUS is illegal and returns an error. Note 

that .SAVESTATUS is legal only on files which are not on magtape oar 
cassette. 

| Macro Call: .SAVESTATUS .area, .chan, .cblk 

where: .cblk is the address of the user memory block (!5 

words) where the channel status information 
is to be stored. 

Request Format: 

RO *> .area: 



5 ! .chan 



.cblk 



The five words stored are the five words normally contained in the 
channel area, as follows: 

Word # Contents 

1 Channel status word. The contents of the bits of 
this word are: 

Bit # Contents 

1 - a hardware error occurred on this 
channel. 
1-5 Index into monitor tables. This describes 
the physical device with which the channel is 
associated. 

6 1 - a .RENAME operation is in progress on the 
channel. 

7 1 - a .CLOSE operation must rewrite the 
directory (i.e., set when a .ENTER is done). 

8-12 Contains the directory segment number 
(1-37(8)) in which the current open file can 
be found. 

13 1 - An end-of-file was found on the channel. 

14 Unused. 

15 1 - This channel is currently in use (i.e., a 
file is open on this channel) . 

2 Starting block number of the file. Zero for 

sequential-access devices. 

3 Length of file (in 256-word blocks) . 

4 Data length of file; currently unused. 

5 Even Bytes I/O count. Count of how many I/O 
requests have been made on this channel. Odd Byte: 
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unit number of the device associated with the channel 
(between - 7) . 

While the .SAVESTATUS/. REOPEN combination is very useful, care must be 
observed when using it. In particular, the following cases should be 
avoided : 

1. If a .SAVESTATUS is performed and the same file is then 
deleted before it is reopened, it becomes available as an 
empty space which could be used by the .ENTER command. If 
this sequence occurs, the contents of the file supposedly 
saved will change. 

2. Although the device handler for the required peripheral need 
not be in memory for execution of a .REOPEN, if the handler 
is not in memory when a .READ or .WRITE is executed, a fatal 
error is generated. 

Errors : 



Code 



Explanation 

The file was opened via .ENTER, or is a magtape or 
cassette file, and a .SAVESTATUS is illegal. 



Example : 

One of the more common uses of .SAVESTATUS and .REOPEN is to 
consolidate all directory access motion and code at one place in the 
program. All files necessary are opened and their status saved, then 
they are re-opened one at a time as needed. USR swapping can be 
minimized by locking in the USR, doing .LOOKUPS as needed, using 
.SAVESTATUS to save the file data, and then .UNLOCKing the USR. 



In the program segment below, three input files are specified 
command string; these are then processed one at a time. 



in the 



.MCALL 
.MCALL 

..VS.. 

.REGOEF 



. ,V2,,,.PtGDEF,,C SI SEN,, 8* VEST A TUB,, REOPEN 
.READ, .EXIT 



START! MOV #AREA,R9 

.C8IGEN *D8P>ACE,#DEXT 



MOV 



R0.BUFF 



ICET INPUT FILES 

ISAVE POINTER TO FREE CORE 



.SAVESTATUS R5,#S»*BL0CK1 (SAVE FIRST INPUT FILE 
.SAVESTATUS R5, #<l, •BL0CK2 (SAVE SECOND FILE 
.SAVESTATUS R5, #5, •8L0CK3 (SAVE THIRD FILE 



MOV #BL0CK1,M 
PROCESS! .REOPEN R5,#0,R« 



IREOPEN FILE ON 
(CHANNEL 



,REA0 R5,#0,BUFF»COUNT, BLOCK (PROCESS FILE ON CHANNEL 

OONEI ADO #12, R4 (POINT TO NEXT SAVESTATUS BLOCK 

CMP R«,#BL0CK3 (LAST FILE PROCESSED? 
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BLQV 
.EXIT 

BIOCKH .WORD 

BLOCKH .WORD 

SU0CK3I .WORD 

AREA I .BLKW 

BUFFI .WORD 
BtOCKj ,W0R0 
COUNT! ,WQRO 

DEXTI .WORD 
OSPACE", 

.END 



PROCESS 

0»0, 9, 0»0 
8, 0, 8, 0, 
0r 0»0> BUG 

10 



266, 

0» f 0r 

START 



JNO • 00 NEXT 



IHEMORV BLOCKS FOR 
I8AVESTATU3 INFORMATION 



.SDAT/SDATC/SDATW 



9.4.35 .SDAT/.SDATC/.SDATW 

These requests are used in conjunction with the . RCVD/ . RCVDW/ » RCVDC 
calls to allow message transfers with RT-11. .SDAT transfers can be 

considered similar to .WRITE requests in which data transfer is not 
from a peripheral, but from one job to another. Additional I/O queue 
elements should be allocated for buffered I/O operations in .SDAT and 
.SDATC requests (see .QSET) . 



.SDAT 

Macro Call: 
where : 



•SDAT .area, .buff, .went 



.buff 



.went 



is the buffer address of the beginning of the 
message to be transferred. 

is the number of words to transfer. 



Request Format: 



R0 ^ .area: 



Errors : 
Code 



25 



unused 



.buff 



.went 



Explanation 

No other job exists. 
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Example : 

See the example following .SDATW. 

.SDATC 

Macro Call: .SDATC .area, .buff, .went, .crtn 



where: .buff 

.went 
• crtn 



is the buffer address of the beginning of the 
message to be transferred. 

is the number of words to transfer. 

is the address of the completion routine to 
be entered when the message has been 
transmitted (refer to Section 9.2.8). f 



Request Format: 



RO 4 .area: 



unused 



25 



.buff 



.went 



,. crtn 



Errors : 

Code Explanation 

No other job exists. 
Example : 
See the example following .SDATW. 



.SDATW 

Macro Call .SDATW .area, .buff, .went 
where: .buff 



.went 
Request Format: 


is 


the i 


RO «* .area: 


25 







unused 




.buff 




.went 








is the buffer address of the beginning of the 
message to be transferred 

is the number of words to transfer 
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Errors : 

Code Explanation 

No other job exists. 
Example : 

In this example, the job first sends a message interrogating the other 
job about the status of an operation, and then looks for an 
acknowledgement from the job. 

.MCAuL . ,V2,,, 1 REG0EF,,SDAT, .RCVD, ,MWA IT, .PRINT, .EXIT 



.RE6DEF 



STARTl 



MOV 

.SOAT 

BCS 



#AREA,R5 f SET UP EMT BLOCK 
R5,#S8UFP,#MLGTH /ASK HIM A QUESTION 
NOJQB |N0 OTHER JOB AROUND! 

rMI8CEtLANE0U8 PROCESSING 

.RCVD R5,#BUFF2,i20, ^RECEIVE 20 DECIMAL WORDS 

• MW *H IWAIT FOR ACKNOWLEDGE. 

MOV #BUFF2*2,Rt IPOINT TO ACTUAL ANSWER. 

CMPB (Ri)*,#«Y MS FIRST WORD Y FOR TEST 

BNE PRNEG fNEGATIVE ACKNOWLEDGE 

.PRINT #P08ACK 

.EXIT 

PRNEGI .PRINT iNEGACK 

.EXIT 

SBUFFl .ASCII /IS THE REQUIRED PRQCES8 GOINGT/ 
MLGTHt.-SBUFF 

9UFF2I .WORD IACTUAL LENGTH IS HERE 

.BLKW 20. ISPACE FOR 20. WORDS 

NOJOBl .PRINT iNJMSG 

.EXIT 

NEGACKI .ASCiZ /NEGATIVE ACKNOWLEDGE/ 

P08ACKI .ASCIZ /POSITIVE ACKNOWLEDGE/ 

NJMSGI .ASCIZ /NO JOB/ 

.EVEN 

AREAI .BLKW 10, 



INEGATIVE ON OUR INQUIRY 



.END 



START 



.SETTOP 



9.4.36 .SETTOP 

The .SETTOP request allows the user program to request that a nevr 
address be specified as a program's upper limit. The monitor 
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determines whether this address is legal and whether or not a memory 
swap is necessary when the USR is required. For instance, if the 
program specified an upper limit below the start address of USR, no 
swapping is necessary, as the USR is not overlaid. If .SETTOP from 
the background specifies a high limit greater than the address of the 
USR and a SET USR NOSWAP command has not been given, a memory swap is 
required. Section 9.2.5 gives details on determining where the USR is 
in memory and how to optimize the .SETTOP. 

On return from .SETTOP, both RO and the word at location 50 (octal) 
contain the highest memory address allocated for use. If the job 
requested an address higher than the highest address which is legal 
for the requesting job, it is adjusted down to that address. 

Macro Call: .SETTOP .addr 

where: .addr is the address of the word immediately 

following the free area desired. 



Notes : 



1. A program should never do a .SETTOP and assume that its new 
upper limit is the address it requested. It must always 
examine the returned contents of RO or location 50 to 
determine its actual high address. 

2. In Version 1 of RT-11, .SETTOP did not return the high | 
address in RO, but only in word 50. 

3. It is imperative that the value returned in RO or location 50 
be used as the absolute upper limit. If this value is ever 
exceeded, vital parts of the monitor may be destroyed, and 
the system integrity will be violated. 

Errors : 

None. 

Example: 

Following is an example in two parts. The first indicates how a 
small background job (i.e., one with free space between itself and the 
USR) can be assured of reserving space up to but not including the USR. 
This in effect gives the job all the space it can without causing the 
USR to become non-resident. 

The second part indicates how to always reserve the maximum amount of 
space by making the USR non-resident. 

I) .MCAU ,,V2,,,,REGDEF, .SETTOP, .EXIT 

• • * * i i 
.REGDEF 

START! 

HM0N»S<» IPOINTER TO START OF RESIDENT 

USRi2bfc fOFFSIT FROM RESIDENT TO POINTER 

INHERE USR MILL START. 



I 



9-83 July 1975 



Programmed Requests 



II) 



MQV ##PM0N,R1 

MOV US» (■»!), »0 

TST .(901 

.SETTOP 

MOV R0.HICORE 



.SETTQP #-2 



MOV 

• EXIT 
HICOREI .WORD 
.END 



R0,HICORE 




START 



>START OF RMON TO Rl 

IPCIINT TO LOWEST USR WORO 

IPOINT TO HIGHEST WORD NOT IN US" 

IAND ASK FOR IT 

>R0 CONTAINS THE HIGH ADDRESS 

(THAT WAS RETURNED. 

(IF WE ASK FOR A VALUE GREATER 
ITHAN START OF RESIDENT. WE 
JWILL GET BACK THE ABSOLUTELY 
IHIGHEST USABLE ADDRESS. 
ITHAT IS OUR LIMIT NOW 



NOSWAP command is executed, the USR cannot be made 

I & II above, RO would return a 



If a SET USR 

non-resident. In this case, in both 

value just below the USR. 

Caution should be used concerning 
background program is so large that 
over part of it, the high limit value returned 
actually be lower than the original limit 
with a portion of the user program destroyed 



technique 
the USR is 



I, above. If the 

normally positioned 

by the .SETTOP may 

The USR is then resident, 

The example in Section 




shows how to include checks that will avoid this situation. 



9.4.37 .SFPA 

.SFPA allows users with floating point hardware (FPP on 11/45 and FIS 

on 11/40) to set trap addresses to be entered when a floating point 

exception occurs. If no user trap address is specified and a floating 

point (FP) exception occurs, a ?M-FP TRAP occurs, and the job is 
aborted. 



Macro Call: .SFPA .area, .addr 



where : . addr 

Request Format: 

RO $ .area: 



is the address of the routine to 
when an exception occurs. 



be entered 



30 



.addr 



Notes : 



If the address argument is 0, user floating point routines 
are disabled and the fatal 7M-FP TRAP error is produced. 

In the F/B environment, an address value of 1 indicates that 
the FP registers should be switched when a context switch 
occurs, but no user traps are enabled. This allows both jobs 
to use the FP unit. An address of 1 to the Single-Job 
Monitor is equivalent to an address of 0. 
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3. When the user routine is activated, it is necessary to 
re-execute an .SPPA request, as the monitor inhibits user 
traps when any one is serviced. It does this to inhibit any 
possible infinite loop being set up by repeated FP 
exceptions . 

4. If the 11/45 FPP is being used, the instruction STST -(SP) is 
executed by the monitor before entering the user's trap 
routine. Thus, the trap routine must pop the two status 
words off the stack before doing an RTI. The program can 
tell if FPP hardware is available by examining the 
configuration word in the monitor (see Section 9.2.6). 

Errors t 

None. 

Example : 

This example sets up a user FP trap address. 

-MCALU ..va..,.PEr,DFF,,SFPA,,FxTT 
..V2., 

.REGREF 



STARTi 



.SFPA #A»EA,#FPTRAP 
.EXIT 



FPTRAPl 



ARFAJ 



MOV 
.SFpA 
MOV 
RTI 

,BUW 

,EN D 



*0,-(5P) 

#APEA,*pPTRAP 

(SP)+,R0 



10 
START 



»Rfl USED BY .SPPA 
IRFSTORE RW 



.SPFUN 



9.4.38 .SPFUN 

This request is used principally with cassettes and magtape, 
handlers to do device-dependent functions, such as rewind and 
backspace, to those devices. (It may also be used with diskette to | 
allow reading and writing of absolute sectors; specific information is 
in Appendix H. ) 

Macro Call: .SPFUN .area, .chan, .code, .buff, .went, .blk, .crtn 



where : . code 



is the numerical code of the function 
performed 



to be 
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• buff 
.crtn 



Request Format: 
RO $ 



is the buffer address; this parameter must be 
set to zero if no buffer is required. 

is the entry point of a completion routine. 
If left blank, is automatically inserted. 



area: 


32 


.chan 




.blk 




.buff 




.went 




,code| 377 




.crtn 



All other arguments are the same as those defined for .READ/. WRITE 
requests (Sections 9.4.30 and 9.4.47). They are only required when 
doing a .WRITE with extended record gap to MT. If the .crtn argument 
is left blank, the requested operation will complete before control 
returns to the user program. ,crtn=l is equivalent to executing a 
.READ or .WRITE in that the function is initiated and returns 
immediately to the user program. A .WAIT on the channel ensures that 
the operation is completed. If ,crtn«*N, it is taken as a completion 
routine address to be entered when the operation is complete. 

The available functions and their codes are: 



Function 



MT 



CT 



Forward to last file 




377 


Forward to last block 




376 


Forward to next file 




375 


Forward to next block 




374 


Rewind to load point 


373 


373 


Write file gap 




372 


Write EOF 


377 




Forward 1 record 


376 




Backspace 1 record 


375 




Write with extended 






file gap 


374 




Offline 


372 





To use the .SPFUN request, the handler must be in memory and a channel 
associated with a file via a .LOOKUP request. 

Refer to Appendix H for details of MT and CT handlers. 

Errors : 

Errors are detected in the same way as for the .READ/.READC/.READW 
requests. Refer to Section 9.4.30 for details. 

Example : 

The following example rewinds a cassette and writes out a 256-word 
buffer and then a file gap. 

.MCAU , ,V2,,, .REGOEF, .FETCH, , LOOKUP* , 5PFUN, , Wft ITW 
.MCALL .EXIT,. PRINT,, WAIT,. CLOSE 

..ve.. 

.REGOEF 



STARTl 



.FETCH iM8PC»#CT 



ISET A HANDLER 
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AREAI 

FERRl 

LKERRl 

3PERRJ 

WTERRl 

OONEt 

FM3SI 

UKM55I 

SPMSGl 

WTM5CI 

CTI 

BUFFI 

BLKI 

HSPCi, 



scs 

.LOOKUP 

acs 

.SPFUN 

BCS 

NOV 

.VRITW 

SCS 

, SPFUN 

, PRINT 

.WAIT 

.CLOSE 

.EXIT 

.BL<W 

.PRINT 

.EXIT 

.PRINT 

.EXIT 

.PRINT 

.EXIT 

.PRINT 

.EXIT 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.EVEN 

.RAOS0 

.WORD 

.BLKW 

.WORD 

,ENO 



FERR IFETCH ERROR 

#ARCA,*4,«CT ILOOK IT UP ON CHANNEL « 
LKERR ILOOKUP ERROR 

#AREAi#4,#173,#? t REWIND SYNCHRONOUSLY 
IPERR IAN ERROR OCCURRED. 

*3,R5 ICOUNT 

IBLOCK 0, 
#AREA,#a,#BUFF,#256.,BLK 
WTERR 

#AREA,#4,#372,*0,, #1 f ASYNCHRONOUS FTLF RAP 
• DONE 

#<* IWAIT FOR DONE 

<M 1CLOSE THE PILE 



PPMSG 



#LKMSS 

#8PH8S 

*WTMSS 

/ALL DONE/ 

/FETCH?/ 

/FILE?/ 

/SPECIAL FUNCTION ERROR/ 

/WRITE ERROR/ 

/CT / 
9,Z,Z 
25b. 
Z 

START 



.SPND/RSUM 



9.4.39 .SPND/.RSUM (F/B only) 

The .SPND/.RSUM requests allow a job to control execution of its 
mainstream code (that code which is not executing as a result of a 
completion routine) . .SPND suspends the mainstream and allows only 
completion routines (for I/O and mark time requests) to run. .RSUM 
from one of the completion routines resumes the mainstream code. 
These functions enable a program to wait for a particular I/O or mark 
time request by suspending the mainstream and having the selected 
event's completion routine issue a .RSUM. This differs from the .WAIT 
request, which suspends the mainstream until all I/O operations on a 
specific channel have completed. 

.SPND 



Macro Call: .SPND 
where: RO ^ 
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.RSUM 

Macro Call: .RSUM 

where: RO £ 
Notes : 



1. The monitor maintains a suspension counter for each job. 
This counter Is decremented by .SPND and Incremented by 
.RSUM. A job will actually be suspended only if this counter 
Is negative. Thus, If a .RSUM Is Issued before a .SPND, the 
latter request will return Immediately. 

2. A program must Issue an equal number of .SPNDs and .RSUMs. 

3. A .RSUM request from the mainstream code increments the 
suspension counter. 

4. A .SPND request from a completion routine decrements the 
suspension counter, but does not suspend the mainstream. If 
a completion routine does a .SPND, the mainstream continues 
until it also issues a .SPND, at which time it is suspended 
and will require two .RSUMs to proceed. 

5. Since a .TWAIT is simulated in the monitor using suspend and 
resume , a . RSUM issued from a completion routine without a 
matching .SPND may cause the mainstream to continue past a 
timed wait before the entire time interval has elapsed. 

6. A .SPND or .RSUM, like most other programmed requests, may be 
issued from a user-written interrupt routine if the .INTEN/ 
.SYNCH sequence is followed. All notes referring to .SPND/ 
.RSUM from a completion routine also apply to this case. 



Errors : 

None. 

Example : 

In this example, the program starts a number of read operations and 
suspends itself until at least two of them are complete. 

.MCALL . . V2 ,,,, REGOEF ,. SPND,, RSUM,. RE ADC. EXIT, .LOOKUP 
.MCALL .PRINT, .WAIT 

,.va.. 

.REGDEF 



START! 



.LOOKUP •AREA,#2,#FILE2 

BCS IS 

.LOOKUP *AREA,«3,»FILE3 

BCS IS 

•LOOKUP «AREA,#4,*FILE4 

SCC 3S 
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i£S 


.EXIT 




.ASCIZ 


/LOOKUP ERROR/ 


.EVEN 
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1SI 
2SI 
311 

MOV #2,R8VCTP JWAIT FOR 2 COMPLETIONS 

MOV #AREA,R5 

.RE ADC R5,#2,#BUFl,C0UNTi,#CR0UTN,BL0Ki 

BC8 ERROR 

.RE ADC R3,#3,#BUF2,C0UNT2,#CR0UTN,6L0K2 

BCS ERROR 

.RE ADC R5,*4,#BUF3, COUNTS, «CROUTN,BLQK 3 

BCI ERROR 

,8PN0 

.WAIT it 

.WAIT *S 

,wAIT #« 
.EXIT 

CROUTNI A8L RJ >OOUBLE CHANNEL • FOR INDEXINS 

INC DONEFL(Ri) |Rt*CHANNEL THAT IS DONE 

>SET A FLAG SAVING SO, 

ROR R0 »ANY ERRORS? 

AOC ERRFLG(Rl) I IF CARRY SET, SET ERROR FLAG FOR CHANNEL 

DEC RSVCTR »ARE WE THE SECOND TO FINISH? 

BNE IS »NO 

,R»UM >YE3, START UP 

I SI RTS PC 



IRRORl .PRINT iROMSG 

.EXIT 

ROMSGl .ASCIZ /READ ERROR/ 

.EVEN 

AREA! ,BLKW 10 

W8VCTRI .WORO 

COUNT1I ,WOKO 836. 

C0UNT2I .WORD 256, 

C0UNT3I ,wOHD 256. 

BLOK18 .WORD 

Bt,0K2l .WORD 

BL0K3I .WORD 

FILE2I .RAO50 /DK TEST2 TMP/ 

FILE3I .RAD50 /DK TESTS TMP/ 

FILE1! .RAD50 /DK TESTA TMP/ 

DONEFLl .WORD 0,0,0 

ERRFLGl .WORD 0,0,0 

BUFH .BLKW 256, 

ByF2l ,BLKW 256. 

BUF31 ,6L*W 256. 



,ENO START 



9-89 



Programmed Requests 



.SRESET 



9.4.40 .SRESET 

The .SRESET (software reset) request performs the following functions: 

1. Dismisses any device handlers which were brought into memory 
via a .FETCH call. Handlers which were loaded via the 
Keyboard Monitor LOAD command remain resident, as does the 
system device handler. 



2. 



3. 



Purges any currently open files. Files opened for output 
with .ENTER will never be made permanent. 

Reverts to using only 16 (decimal) I/O channels. Any 
channels defined with .CDFN are discarded. A .CDFN must be 
reissued to open more than 16 (decimal) channels after a 
•SRESET is performed. 



Resets the I/O queue to one element. A 
reissued to allocate extra queue elements. 



.QSET 



must be 



5. Clears completion queue of any completion routines. 

Macro Call .SRESET 

Errors : 

None. 

Example t 

In the example below, .SRESET is used prior to calling the CSI to 
ensure that all handlers are removed from memory and the CSI is 
started with a free handler area. 

.MCALL , .V2,,,,REGDEF,.CSIGEN,. SRESET. .EXIT 

..V2,. 

.HEGOEF 

STARTl .CSICEN *D3PACE,#DEXT,#0 JGET COMMAND STRING 

MOV R0, BUFFER >R0 POINTS TO FREE MEMORY 



00NEI .SRESET 

SR START 



(RELEASE HANDLERS, DELETE 
ITENTATIVE FILES 
IAN0 REPEAT PROGRAM, 
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OEXTl .WORD 8,0,0,0 

BUFFER! 

DSPACEs, 



INO DEFAULT EXTENSIONS 
JSTART OF HANDLER AREA, 



.CND 



START 



If the .SRESET had not been performed prior to the second call of 
.CSIGEN, it is possible that the second command string would load a 
handler over one that the monitor thought was resident from the first 
command line. 



TLOCK 



9.4.41 .TLOCK 

.TLOCK is used in an F/B system to attempt to gain ownership of the 
USR. It is similar to .LOCK in that if successful, the user job 
returns with the USR in memory. However, if a job attempts to .LOCK 
the USR while the other job is using it, the requesting job is 
suspended until the USR is free. With .TLOCK, if the USR is not 
available, control returns immediately with the C bit set to indicate 
the .LOCK request failed. 

Macro Call: .TLOCK 

The .TLOCK request allows the job to continue running, with only one 
sub-job affected. With a .LOCK request, all sub-jobs would be 
automatically suspended, and the other job in the system would run. 

Request Format: 

RO : # area : 

Errors : 



7 



Code 



Explanation 

USR is already in use by another job. 



Example : 

In the following example, the user program needs the USR for a sub- job 
it is executing. If it fails to get the USR it suspends that sub-job 
and runs another sub-job. This type of procedure is useful to 
schedule several sub- jobs within a background or foreground program. 

.MCALL ,.V2,,,,REGDEF,, TLOCK, , LOOKUP , .UNLOCK, .EXIT, .PRINT 

• • V2 . , 

.REGOEF 

STARTI 
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.TLOCK IGET THE USR 

BC3 8U8PNQ fFAILED, SUSPEND SUB-JOB 

.LOOKUP #AREA,#<t,#JJ.NAM HOOKUP A FILE 

BCS LKERR 

.UNLOCK ^RELEASE USR 



.EXIT 



SU3PNDI JSR 
JSR 



PC.SP840B 
PC»8CHED 



I8USPEND SUB-JOB 

IAND SCHEDULE NEXT USER 



AREAI .BLKM 
JiNAMl .HAD50 
LKERRl .PRINT 

.EXIT 
LKMSGl .ASCIZ 

.EVEN 
SPSJOBI RTS 
SCHEOI RTS 

.END 



10 

/DK TE8TI TMP/ 
#LKMS6 

/LOOKUP ERROR/ 

PC 
PC 

START 



TRPSET 



9.4.42 .TRPSET 

.TRPSET allows the user job to Intercept traps to 4 and 10 instead of 
having the job aborted with a 7M-TRAP TO 4 or 7M-TRAP TO 10 message. 
If .TRPSET is in effect when a trap occurs, the user-specified routine 
is entered. The sense of the C bit on entry to the routine determines 
which trap occurred t C bit clear indicates a trap to 4; set indicates 
a trap to 10. The user routine should exit via an RTI instruction. 

Macro Callt .TRPSET .area, .addr 



is the address of the user's trap routine. 
If an address of is specified, the user's 
trap interception is disabled. 



.addr 



where t . addr 

Request Format: 

R0 «p .area i 

Notes % 

It is necessary to reissue a .TRPSET request whenever a trap occurs 
and the user routine is entered. The monitor inhibits servicing user 
traps prior to entering the first user trap routine. Thus, if a trap 
should occur from within the user's trap routine, a 7M-TRAP message is 
generated. The last operation the user routine should perform before 
an RTI is to reissue the .TRPSET request. 
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Errors : 

None. 

Example : 

The following example sets up a user trap routine and, when the trap 
occurs, prints an appropriate error message. 

.MCALL ,.V2,.,.REG0EF,, TRPSET, .EXIT,, PRINT 
,.V2,, 



STARTl 



.REGOEP 



.TRPSET *AREA,#TRPLOC 

MOV #101, R0 ISET TO PRODUCE A TRAP 

TIT (R0)* ITHIS WILL TRAP TO 4. 

•WORD *7 >THIS WILL TRAP TO 10, 

.EXIT 



TRPLfCl MQV R0,-fSP) IRR USFD BV fMTS 

BCS IS |C SET a TRAP TO 10 

.PRINT #TRP4 ITRAP TO 4 

8R 2$ 

lit .PRINT #TRP10 ITRAP TO 10 

211 , TRPSET #AREA,#TRPLOC »RESET TRAP ADDRESS 

MOV CSP)*,R0 IRPSTORE Rfl 
RTI 



AREAI ,BLKW 10 

TRP4I .ASCIZ /TRAP T0 4/ 

TRP10I .ASCIZ /TRAP TB 10/ 
.EVEN 

.END START 



JTYIN/TTINR 



9.4.43 . TTYIN/TTINR 

These requests are used to transfer characters from the console 
terminal to the user program. The character thus obtained appears 
right- justified (even byte) in RO. 
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The expansion of .TTYIN is: 

EMT 340 
BCS .-2 

while that for .TTINR is: 

EMT 340 

If no characters or lines are available when an EMT 340 is executed, 
return is made with the C bit set. The implication of these calls is 
that .TTYIN causes a tight loop waiting for a character/line to 
appear, while the user can either wait or continue processing using 

.TTINR. 

Macro Calls: .TTYIN .char 

.TTINR 

where: .char is the location where the character in RO is 

stored. If not specified, the character is 
left in RO. 

If the carry bit is set when execution of the .TTINR request is 
completed, it indicates that no character was available; the user ha.s 
not yet typed a valid line. Under the P/B Monitor, .TTINR does not 
return the carry bit set unless bit 6 of the Job Status Word was on 
when the request was issued (see below) . 

There are two modes of doing console terminal input. This is governed 
by bit 12 of the Job Status Word. If bit 12 ■ 0, normal I/O is 
performed. In this mode, the following conditions apply: 

1. The monitor echoes all characters typed; lower case 
characters are converted to upper case. 

2. CTRL U (tU) and RUBOUT perform line deletion and character 
deletion, respectively. 

3. A carriage return, line feed, CTRL Z, or CTRL C must be 
struck before characters on the current line are available to 
the program. When carriage return is typed, characters on 
the line typed are passed one- by-one to the user program; 
both carriage return and line feed are passed to the program. 

4. ALTMODEs (octal codes 175 and 176) are converted to ESCAPES 

(octal 33) . 

If bit 12 » 1, the console is in special mode. The effects are: 

1. The monitor does not echo characters typed except for CTRL C 
and CTRL O. 

2. CTRL U and RUBOUT do not perform special functions. 

3. Characters are immediately available to the program. 

4. No ALTMODE conversion is done. 

In special mode, the user program must echo the characters received. 
However, CTRL C and CTRL O are acted on by the monitor in the usual 

9-94 



Programmed Requests 



way. Bit 12 in the JSW must be set by the user program, 
cleared when control returns to RT-11. 



This bit is 



CTRL F and CTRL B are not affected by the 
monitor always acts on these characters. 



setting of bit 12, 



The 



the 



CTRL S and CTRL Q are intercepted by the monitor (unless, under 
F/B monitor, the SET TTY NOPAGE command is issued) . 

Under the F/B Monitor, if a terminal input request is made and no 
character is available, job execution is blocked until a character is 
ready. This is true for both .TTYIN and .TTINR, and for both normal 
and special modes. If a program really requires execution to continue 
and the carry bit to be returned, it must turn on bit 6 of the JSW 
(location 44) before the .TTINR request. Bit 6 is cleared when a 
program terminates. 



Errors : 

Code 



Explanation 



No characters available in ring buffer. 
Example t 
Refer to the example following the description of .TTYOUT/.TTOUTR. 



TTYOUT/XTOUTR 



9.4.44 . TTYOUT/ . TTOUTR 

These requests cause a character to be transmitted from RO to the 
console terminal. The difference, as in the .TTYIN/. TTINR requests, 
is that if there is no room for the character in the monitor's buffer, 
the .TTYOUT request waits for room before proceeding, while the 
.TTOUTR does not wait for room and the character in RO is not output. 

Macro Calls: .TTYOUT .char 



.TTOUTR 
where : . char 



is the location containing the character to 
be loaded in RO and printed. If not 
specified, the character in RO is printed. 
Upon return from the request, RO still 
contains the character. 

If the carry bit is set when execution of the .TTOUTR request is 
completed, it indicates that there is no room in the buffer and that 
no character was output. Under the F/B Monitor, .TTOUTR normally does 
not return the carry bit set. Instead, the job is blocked until room 
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is available in the output buffer. If a job really requires execution 
to continue and the carry bit to be returned, it must turn on bit 6 of 
the Job Status Word (location 44) before issuing the request. 

The .TTINR and .TTOUTR requests have been supplied as a help to those 
users who do not wish to suspend program execution until a console 
operation is complete. With these modes of 1/0, if a no-character or 
no-room condition occurs, the user program can continue processing and 
try the operation again at a later time. 

Notet 

If a foreground job leaves bit 6 on in the JSW, any further foreground 
.TTYIN or .TTYOUT requests will cause the system to lock out the 
background. Note also that each partition has its own JSW, and 
therefore can be in different terminal modes independently. 

Errors t 

Code Explanation 

Output ring buffer full. 

Example : 

As an example of the various terminal requests, the following program 
is coded in two ways. The program itself accepts a line from the 
keyboard, then repeats it on the terminal. 

The first example uses .TTYIN and .TTYOUT, which are synchronous. The 
monitor retains control until both requests are satisfied, hence there 
is no time available for any other processing while waiting. 

.MCAUL .,V2,.,.REGDEF,, TTYIN,. TTYOUT 

..V2.. 

.RECDEF 

STARTl MOV #BUFF|R,R1 IPOINT Rl TO BUFFER 

CUR R2 ICLEAR CHARACTER COUNT 

XNUOOPI , TTYIN CRl )♦ IREAO CHAR INTO BUFFER 

INC Ri fBUMP COUNT 

CMPB #11, RB |WAS LAST CHAR«|.F? 

BNE INL00P- »N0-6ET NEXT 

MOV #BUFF|R,RJ IYES-POINT Rl TO BUFFER 

OUTIOOPI .TTYOUT (Rl)* >PRINT CHAR 

DEC R2 (DECREASE COUNT 

BEQ START IDONE IF COUNT ■ 

BR OUTLOOP 

BUFFER*, 

.END START 

Rather than wait for the user to type something at INLOOP or wait for 
the output buffer to have available space at OUTLOOP, the routine can 
be recoded using .TTINR and .TTOUTR as follows: 
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.MCALL ..va.,,.REGDEF..TTYIN,.TTYOUT 

• ■ " c * • 

.REGDEF 

.MCALL .TTINR,, TTOUTR,. FXIT 



START! MOV #BUFF6»,R1 »PQINT Rl TO BUFFER 

CLR R3 (CLEAR CHARACTER COUNT 

BIS #100,#>#aa |WE REALLY WANT CARRY SET 

INLOOPt .TTINR (GET CHAR FROM TERMINAL 

BCS NQCHAR (NONE AVAILABLE 

CHRINI M0V8 R0.CRU+ (PUT CHAR IN SUFFER 

INC R8 HNCREASE COUNT 

CMPB R0,#18 IWAS LAST CHAR • LF? 

BNE INLOOP (NO-GET NEXT 

MOV #8UFFER»R1 (YES-POINT Rl TO BUFFER 

OUTLOOP» MOVB CRH.R0 |PUT CHAR IN R0 

TTOUTR ITYPEIT 

BCS NOROOM (NO ROOM IN OUTPUT BUFFER 

CHROUTl DEC R2 (DECREASE COUNT 

BEQ START (DONE IF COUNT»C3 

INC Rl (BUMP BUFFER POINTER 



NOCHARl 



BR OUTLOOP (AND TYPE NEXT 



.TTINR (PERIODIC CHECK FOR 

CHARACTER AVAILABILITY 
BCC CHRIN (GOT ONE 



NQRQOMi 



(code to be executed 
while waiting) 



BR NOCHAR 



MOVB (Rl),R0 (PERIODIC ATTEMPT TO TYPE 

(CHARACTER 
.TTOUTR 
BCC CHROUT (SUCCESSFUL 

(code to be executed 
while waiting) 



TYPEITl BIC #100,##4« (MUST CLEAR THIS BIT 

(SO HANG WHILE 
(WAITING FOR ROOM, 
.TTYOUT (Rl) (PUT CHAR 

BIS #100,»#<U (RESTORE NO-WAIT 
BR CHROUT 



BUFFERI ,BLKW 100. 
.END START 
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Example : 

For an example of .WAIT used for I/O synchronization, see the examples 
in the next section. 

An example of the use of .WAIT for error detection is its use in 
conjunction with .CSIGBN to determine which file fields in the command 
string have been specified. For example, a program such as MACRO 
might use the following code to determine if a listing file is 
desired. 

.MCAU . ,V2,,,,R£GDEF,,WAIT,,CSIGEN lt EXIT 

..V2,. 

.RECDEF 



STARTl 



.C8IGEN #OSPACE,*DEXT,#0 IPROCESS COMMAND STRING 



.WAIT 
BCS 



me 

NOBINARY 



JCHECK FOR FILE IN FIRST FIELD 
INO BINARY DESIRED 



NQBINARYI 



.WAIT 
BCS 



ii 

NOLISTING 



JCHECK FOR LISTING SPECIFICATION 
;N0 LISTING DESIRED 



NOLISTING! 



ERRORl 
DEXTI 

DSPACE", 



,MAIT 
BCS 

.EXIT 



.END 



#3 
ERROR 



.RADS0 /MAC/ 

,RAO50 /OBJ/ 

.RAD50 /LST/ 

.WORD 



START 



ICMECK FOR INPUT FILE OPEN 
INO INPUT FILE 



.WRITE/.WRITC/.WRITW 



9.4.47 .WRITE/.WRITC/.WRITW 

Note that in the case of .WRITE and .WRITC, additional queue elements 
should be allocated for buffered I/O operations (see .QSET) . 

.WRITE 

The .WRITE request transfers a specified number of words from memory 
to the specified channel. Control returns to the user program 
immediately after the request is queued. 



January 1976 



9-100 



Programmed Requests 



Macro Call: .WRITE .area, .chan, .buff, .went, .blk 
where x . buff 



Is the address of the memory buffer to be 
used for output. 



.went 
.blk 
Request Format: 

RO =^ .area: 



Is the number of words to be written. 

is the number of the block to be written. 



11 



.chan 



.blk 



.buff 



.went 



Notes : 

See the note following .WRITW. 

Errors: 

Code Explanation 





1 
2 



Attempted to write past end-of-file. 
Hardware error. 
Channel was not opened. 



Example t 

Refer to the examples following .WRITW. 



.WRITC 

The .WRITC request transfers a specified number of words from memory 
to a specified channel. Control returns to the user program 
immediately after the request is queued. Execution of the user 
program continues until the .WRITC is complete, then control passes to 
the routine specified in the request. When an RTS PC is encountered 
in the routine, control returns to the user program. 

Macro Call: .WRITC .area, .chan, .buff, .went, .crtn, .blk 

where: .buff 



• went 



,crtn 



.blk 



is the address of the memory buffer to be 
used for output. 

is the number of words to be written. 



is the address of the completion 

be entered (see Section 9.2.8). 



routine to 



is the number relative to the start of the 
file, not block of the device. The monitor 
translates the block supplied into an 
absolute device block number. The user 
program normally updates .blk before it is 
used again. 
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Request Format: 



RO 4 .area: 



TBlt 



.chan 



TEuTT 
.wcrTE" 



.crtn 



When entering a .WRITC completion function the following are trues 

1. RO contains the channel status word for the operation. If 
bit of RO is set, a hardware error occurred during the 
transfer. The data may not be reliable. 

2. Rl contains the octal channel number of the operation. This 
is useful when the same completion function is to be used for 
several different transfers. 



Notes : 

See the note following .WRITW. 

Errors : 

Code Explanation 

End-of-file on output. Tried to write outside limits 
of file. 

1 Hardware error occurred. 

2 Specified channel is not open. 



Example : 

Refer to the examples following .WRITW. 



.WRITW 

The .WRITW request transfers a specified number of words from memory 
to the specified channel. Control returns to the user program when 
the .WRITW is complete. 

Macro Call: .WRITW .area, chan, .buff, .went, .blk 



where: .buff 
.went 
.blk 



is the address of the buffer to be used for 
output. 

is the number of words to be written. The 
number must be positive. 

is the number of the block to be written. 
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Request Format: 



RO >^ .area: 



£ 



11 .chan 



TblE 
• buff 



.went 







Note: 

Upon return _ from any WRITE programmed request, RO will contain no 
information if the write is to a sequential-access device (for example, 
magtape) . If the write is to a random-access device (disk, DECtape) , 
RO contains the number of words that will be written (.WRITE or .WRITC) 
or have been written (.WRITW). If a request is made to write past the 
end-of-file on a random-access device, the word count is shortened and 
an error is returned. Note that the write will be done and a completion 
routine, if specified, will be entered, unless the request cannot be 
partially filled (shortened word count = 0) . 



Errors : 

Code 


1 
2 

Examples : 



Explanation 

Attempted to write past EOF, 
Hardware error. 
Channel was not opened. 



The following routine illustrates the differences between the three 
types of .READ/.WRITE requests and is coded in three ways, each using 
a different mode of monitor I/O. The routine itself is a simple 
program to duplicate a paper tape. 

In the first example, .READW and .WRITW are used. The I/O is 
completely synchronous, with each request retaining control until the 
buffer is filled (or emptied) . 



.HCALL 
..V2,. 

.&EGDEF 



. •V2..,.R€CDEF,. FETCH,. READt*,, WRITW 
.ENTER,. LOOKUP,, PRINT,, EXIT,. CLOSE,, WAIT 



£RRWD»52 
STARTI 



.FETCH #HSPACE,*PRNAME JGET PR HANDLER 

BCS FERR 

MOV RB,R2 

.FETCH R2,»PPNAME 

BCS FERR 

MOV #AREA,R5 

CLR R4t 

MOV #1,R3 

.ENTER R5,ft«,#PPNAME 

BCS ENERR 



UOOPI 



»PR NOT AVAILABLE 

|R0 HAS NEXT FREE LOCATION 

IGET PP HANDLER 

»N0T AVAILABLE 

IEMT ARGUMENT AREA 

>R<t 18 OUTPUT CHANNfeLl 9 

IRS 13 INPUT CHANNEL ) 1 

IENTER THE FILE 

fSOME ERROR IN ENTER 

/LOOKUP FILE ON CHANNEL i 

IERR0R IN LOOKUP 

IUSE Rl AS BLOCK NUMBER 

R5,R3,#BUFF,#25b.,Rl |R£AD ONE BLOCK 

ROERR 

R5,R«,#BUFF,#256,,Ri IWRITE THAT BLOCK 



.LOOKUP R5,R3,*PRNAME 

BCS LKEMR 

CLR Rl 

.REAOW 

BCS 

.URITW 
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SC5 WTERR 

ISC Rl IBUMP BLOCK. NOTE: THIS IS 

INOT NECESSARY FOR NON-FILE 
IDEVICES IN GENERAL, IT 18 
IUSED HERE AS AN EXAMPLE OF 
JA BENERAL TECHNIQUE. 
JKEEP GOING 
IERROR, IS IT EOF? 
IYES 
|NO, HARD READ ERROR 

ICL05E INPUT AND OUTPUT 

|ANO EXIT. 



JNOTE THAT PR NEEDS NO FILE NAME 
|FILE NAME NEED ONLY BE 0» 





BR 


LOOP 


ROERRJ 


TSTB 


ERRWD 




BED 


I* 




.PRINT 


#RDM5G 




.EXIT 




1*1 


.CLOSE 


R3 




.CLOSE 


Rtt 




.EXIT 




WTERRI 


.PRINT 
.EXIT 


#WTMSG 


PRNAMEt 


.RAQ50 


/PR / 




.WORD 





PPNAMEi 


.RAD5S) 


/PP / 




.WORD 


B 


FERRI 


.PRINT 
.EXIT 


#FNSG 


ENERRl 


.PRINT 
.EXIT 


#EMSG 


LKERRl 


.PRINT 
.EXIT 


• LMSG 


FMSGl 


.ASCIZ 


/NO DEVICE?/ 


EMSGI 


.A3CIZ 


/ENTRY ERROR?/ 


LMSGI 


.ASCIZ 


/LOOKUP ERROR?/ 


ROMSG) 


.ASCIZ 


/READ ERROR?/ 


WTMSGl 


.ASCIZ 

.EVEN 


/KRITE ERROR?/ 


AREAI 


,BLK« 


IB 


BUFFI 


.BLK* 


256. 


HSPACE' 


. 






.END 


START 



IERROR ACTIONS GO HERE, IT IS 
IGENERALLY UNDESIRABLE TO 
IEXECUTE A HALT OR RESET 
INSTRUCTION ON ERROR. 



The same routine can be coded using .READ and .WRITE as follows. The 
.WAIT request is used to determine if the buffer is full or empty 
prior to its use. 

.MCALL .,Ve..,.REGDEF,. FETCH,, READ,. WRITE 
.MCALL . ENTER., LOOKUP,. P«INT,,£X IT,. CLOSE,. WAIT 

,.V2,. 

.RE6DEF 

ERR»D>52 

STARTl .FETCH KHSPACE, tPRNAME |GET PR HANDLER 

BCS FERR »P R NOT AVAILABLE 

MOV R0.R2 >RB HAS NEXT FREE LOCATION 

.FETCH R2,#PPNAME IGET PP HANDLER 

BCS FERR »NOT AVAILABLE 

MOV #AR|A,R5 IEMT ARGUMENT AREA 

ci b r« |RU IS OUTPUT CHANNELI 

MOV #1,R3 >R3 J8 INPUT CHANNEL 11 

.ENTER RS,R*,#PPNAME ItNTER THE FILE 
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LOOPt 



RDERRl 

IOER-PJ 
PRNAMEl 

PPNAMEI 
FERRJ 
ENERRl 
LKERRl 

FM8GI 

EMSGI 
LMSGl 
lOMSGt 
WTMSGl 

AREAI 
BUFFI 

MSPACE*. 



bcs 

.LOOKUP 

BCS 

CL» 

.READ 

BCS 

.WAIT 

BCS 

.WRITE 

BCS 

INC 

8R 

TST8 

0NE 

.CLOSE 

.CLOSE 

.EXIT 

.PRINT 

.EXIT 

.RAD50 

.WORD 

.RAD50 

.WORD 

.PRJNT 

.EXIT 

.PRINT 

.EXIT 

.PRINT 

.EXIT 

.A3CIZ 

.ASCIZ 

, ASCIZ 

.ASCIZ 

.ASCIZ 

.EVEN 

.BLKW 

.61KW 

.END 



ENERR 

RS,R3,*PRNAME 

LKERR 

Rl 



JSOME ERROR IN ENTER 
fLOOKUP FILE ON CHANNEL 1 
TERROR IN LOOKUP 
lUSfc Rl AS BLOCK NUMBER 
Ri JREA0 A 



"1 JW-- ,._.._.„.._ 

R5,R3,#BUFF,#256 if Ri JREAD A BUFFER 
ROERR 

I V**IT FOP BUFFER 
fERROH HERE IS HARD 



j, u n « r> u ERROR 
JWKITE TTHE BUFFER 



R3 

IOERR fERROH HER 

R5,R«,#BUFF,#25fc.,Rl JWHIT 

IOERR II/O ERROR 

Rl 

LOOP >KEEP GOING 

ERRWO JERROR, IS IT EOFT 

IOERR >NO, HARD ERROR 

R3 ICLOSE INPUT AND OUTPUT 

R« 

IAND EXIT, 
OIOMSG |NOf HARD READ ERROR 



/PR / 

/PP / 



#FMSG 

#EMSG 

#LMSG 

/NO DEVICE?/ 
/ENTRY ERROR?/ 
/LOOKUP ERROR?/ 
"I/O ERROR?" 
/fcRITE ERROR?/ 

IB 
256. 

START 



INOTE THAT PR NEEDS NO FILE NAME 
IFILE NAME NEED ONLY BE 0. 



JERROR ACTIONS GO HERE. IT 18 
IGENERALLY UNDESIRABLE TO 
fEXECUTE A HALT OR RESET 
INSTRUCTION ON ERROR, 



.READ and .WRITE are also often used for double-buffered 
basic double-buffering algorithm for input is: 

Explanation 



I/O. The 



LOOP: 



READ 


BUFFER 


1 


WAIT 


BUFFER 


1 


READ 


BUFFER 


2 


USE 


BUFFER 


1 


WAIT 


BUFFER 


2 


READ 


BUFFER 


1 


USE 


BUFFER 


2 


BR 


LOOP 





Fill BUFFER 1 

Wait for BUFFER 1 to fill 

Start filling BUFFER 2 

Process BUFFER 1 while BUFFER 2 fills 

Wait for BUFFER 2 to fill 

Start filling BUFFER 1 

Process BUFFER 2 while BUFFER 1 fills 
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Correspondingly, the basic double-buffering algorithm for output isi 

Explanation 



FILL BUFFER 1 
LOOP: WRITE BUFFER 1 
FILL BUFFER 2 

WAIT BUFFER 1 
WRITE BUFFER 2 
FILL BUFFER 1 

WAIT BUFFER 2 
BR LOOP 



Prepare BUFFER 1 for output 

Start emptying BUFFER 1 

Fill BUFFER 2 while BUFFER ] 

empties 

Wait for BUFFER 1 to empty 

Start emptying BUFFER 2 

Fill BUFFER 1 while BUFFER '< 

empties 

Wait for BUFFER 2 to empty 



The previous example program can be coded using completion routines 
via .READC and .WRITC as follows. Once the initial read is performed, 
the remainder of the I/O is performed by the completion routines. 

.MCAtu ,. Vl..,.*EfiDFF.. FETCH,. RFAnC,. WRITS 

Jmcall .enter,. lookup,. prtnt,. exit,. close.. watt 



,.V2., 
.REGDEF 



ERRBYT*3« 



STARTI 



FLNKl 



LOOP! 



tst 



FOF! 



,ENA*L 
RDCOMpl 



RWFRRI 
WRCOMpI 



.FETCH 

BCS 
MOV 
'.FETCH 

PICS 
MQV 

CI.P- 
MOV 

.ENTFR 

*C8 

'.LOCKUP 

§C» 

CU« 

CL" 

.readc 
bcs 

T$T 

BED 

RMI 

.CLOSE 

.CLOSE 

.EXIT 

LSB 
R0 fi 

«c* 

,W«ITC 

HCC 

MOV 

RT» 

PO* 

BC8 

TNC 

'.RE ADC 

HCC 

TST8 



#HSPACE,*P"NAMF 

FLNK 

P0.R? 

Ra # #PpNAME 

FERR 

#AREA,*3 

Pfl 

#1,R5 

R5,R«,*PPNAMF 

ENFRR 

R5,R!i*P*NAMF 

LKFRR 

*t 

DFLG 

R5,RS,«BUFF,#2^fe 

FOF 

ori'G 
is 

TOFRR 

P3 

R« 



JGFT PP HANDLER 

IPR NOT AVULAPLF 

»RB HAS NEVT FPEF LOCATION 

IGFT PP HANDLES 

»NOT AVAILABLE 

»EMT ARGUMFNT ARfA 

>R<I IS OUTPUT CHANNELl 

»R* IS INPUT CHANNFL 1 1 

IENTFR THE FTLF 

(SOME ERRQP *N ENTFR 

fLOOKUP FUE ON CHANNEL 1 

rEPROR IN I ORKUP 

IUSE Rl *S BLOCK NUMBER 

f CI EAR DONF/FRROP FLAG 

.,#R0C0MP,Ri »»EAD ONE BLOCK 

FNO FRRO* WILL HAPPEN H£PE 

IDANE FLAG SET* 

INP, WAIT FOR TT TO BE SFT*. 

IYFS. P-UT HARD ERROR OCCURRED 

JCLOSE INPUT AND OUTPUT CHANNELS 

(ALL DHNF 



R0 IIF ilT H SET 

RMVRR »AN ERROP OCCURRED. 

#APEA,#0,#PUFF,#?5fc..#WRCOMP,BLKN (WRITE THAT BLOCK 



3$ 

#-1 ,«F 

PC 

P0 

RWFRR 

PLKN 



IERR0R HFRF TS HAROWARF 
IFLAG THE FRRQP 



IHARDWARF FRPQP 
»BHMP BLOCK NUMBFR*. 

#i»EA,#i,#BUFF,#?5*...l»PDC0MP»BLKN 

j$ |Nn ERROR 

FRRiVT IEOF? 
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BNE BWFRR (NO, HARft ERROR 

TNC 0P| C, JSAY WF'RP. DONF 

3$J RTS PC 
.OSABU IS" 

F£RRt MOV #FMSR # »0 (ERROR ACTTONS GO HERE. TT I» 

BR TYPIT IGFNERAULY UNDFSIRABLE TO 

FNFRRI MQV #EM8C,P0 (EXECUTE A HALT OR RFSFT 

MR TY»IT INSTRUCTION ON FRRQR. 

IOFRBJ MOV #IOMSG,Rffl 

BR TYPIT 

LKFRRl MQV *LMSR,R0 
TYPITJ .PRINT 

.EXIT 
.NLIST BFX 

FM8GI .ASCIZ /NO OEVIOEt/ 

FMSGI '.A*CT2 /EWTPY ERROR*/ 

LM8GI .ASCIZ /LOCKUP FR*Oi»/ 

TOMSfti .A8CTZ "I/O fPROR?" 
.LTST *E< 
.EVEN 

OFIGI .WORD H 

PRWAMEI ,RAO^0 /PR / »NOTC THAT PP NEFD« NO FTLF. NAME 

.WORD PI IFTLF NAME NIEO ONLY BF 0. 

PPNAMEl .RAD50 /PP / 

,WORO fl 

PLKNI '.WORO »! IBLOCK NUMBEP 

AREAI .8UW 10 

BUFFI ,(JLKW ?5fc, 
HSPACK*. 

.END START 

The following example incorporates the .LOOKUP, .READW, and .CLOSE 
requests. The program opens the file RT11.MAC which is on the system 

device, SYz, for input on channel 0. The first block is read and the 
file is then closed. 

.MCALL ,,V2.,,,REGDEF,, CLOSE,, LOOKUP 

.MCALL .PRINT, .EXIT, .READ*, .FETCH 

..V2.. 

.REGOEF 

8TART| MOV *LXST,R5 |EMT ARGUMENT LIST POINTER 

CLP R* (BLOCK NUMBER 

CLP R] ICHANNEL * 

.FETCH #C0RA0D,tFFTR (FETCH DEVICE HANDLER 

8CC 2S 

MOV #FETM6G,R0 IFETCH ERROR 
U> .PRINT IPRINT ERROR MESSAGE 

.EXIT 

2$t .LOOKUP R5,R3,«FPTR (LOOKUP FILE ON CHANNEL 

SCC 3* 

MOV #LKMSG,R0 IPRJNT FAILURE MESSAGE 

SH IS 

SSI .READW R5,R3,#BUFF,#25b,,Ra JREA ONE BLOCK 

BCC 44 

MQV #HDMSG,R0 (READ ERROR 

BR JS 

4S« .CLOSE RS (CLOSE THE CHANNEL 

.EXIT 

LIST! ,BLKW 5 ILIST FOR EMT CALLS 

FPTHI. ,RAD5« /SY RTU MAC/ (RAD50 OF FIEL NAME, DEVICE 

FETMSGI .ASCIZ /FETCH FAILED/ | ASCII MESSAGES 

LKMSGI .ASCIZ /LOOKUP FAILED/ 
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RDMSGI .ASCIZ /READ FAILED/ 

.EVEN 
CORADOJ .6LKW 8008 I SPAM FOK LARGEST HANDLERS 

8UFF«, 

,ENQ START 

9.5 CONVERTING VERSION 1 MACRO CALLS TO VERSION 2 

As mentioned in the introduction of this chapter, RT-11 Version 2 
supports a slightly modified format for system macro calls than 
Version 1. This section details the conversion process from the 
Version 1 format to Version 2. 



9.5.1 Macro Calls Requiring No Conversion 

Version 1 macro calls which need no conversion are: 

.CSIGN .RCTLO 

.CSISPC .RELEAS 

.DATE .SETTOP* 

.DSTATUS .SRESET 

.EXIT .TTINR** 

.FETCH .TTOUTR 

.HRESET .TTYIN 

.LOCK .TTYOUT 

.PRINT .UNLOCK 
.QSET 

♦Provided location 50 is examined for the maximum value. 
**Except in F/B System. 

9.5.2 Macro Calls Which May Be Converted 

The following Version 1 macro calls may be converted: 

.CLOSE .RENAME 

. DELETE . REOPEN 

. ENTER . S AVESTATUS 

.LOOKUP .WAIT 

.READ .WRITE 

The general format of the VI macro is: 

.PRGREQ .chan, .arg.L .arg2,. . .argn 

In this form, .chan is an integer between and 17 (inclusive), and 
is not a general assembler argument. The channel number is assembled 
into the EMT instruction itself. The arguments argl-argn are always 
pushed either into R0 or on the stack. 

The V2 equivalent of the above call is: 

.PRGREQ .area, .chan, .argl,. . . .argn 
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In the V2 call, the .chan argument can be any legal assembler 
argument; it need not be in the range to 17 (octal) , but should be 
in the range 0-377 (octal), .area points to a memory list where the 
arguments argl...argn will go. 

As an example, consider a .READ request in both forms: 

VI: .READ 5,#BUFF,#256. , BLOCK 

V2: .READ #AREA, #5,#BUFF,#256. ,BLOCK 



AREA: .WORD ; CHANNEL/FUNCTION CODE HERE 

.WORD ; BLOCK NUMBER HERE 

.WORD ; BUFFER ADDRESS HERE 

.WORD ;WORD COUNT HERE 

.WORD ;A 1 GOES HERE. 

Thus, the difference in the calls is that in Version 2 the channel 
number becomes a legal assembler argument and the .area argument has 
been added. 

Following is a complete list of the conversions necessary for each of 
the EMT calls. Both the Version 1 and Version 2 formats are given. 
Note that parameters inside [] are optional parameters. Refer to the 
appropriate section in this chapter for more details of each request. 

Version Programmed Request 

VI: .DELETE ,chan,.dblk 

V2: .DELETE .area, .chan, .dblk, [.count] 

VI: .LOOKUP .chan,. dblk 

V2 : . LOOKUP . area , . chan , . dblk , [ . count ] 

VI: .ENTER .chan, .dblk, [.length] 

V2: .ENTER . area, .chan, .dblk, [.length] , [.count] 

VI: .RENAME .chan,. dblk 

V2: .RENAME .area,. chan, .dblk 

VI: .SAVESTAT .chan,.cblk 

V2: .SAVESTAT .area, .chan,. cb Ik 

VI: .REOPEN .chan,.cblk 

V2 : . REOPEN . area , . chan , . cblk 

VI: .CLOSE .chan 
V2: .CLOSE .chan 

VI: .READ/.READW .chan, .buff , .went , .blk 

V2: .READ/.READW . area, .chan, .buff , .went, .blk 

VI: .READC . chan,. buff,. went,. crtn,. blk 

V2: .READC .area, .chan, .buff , .went, .crtn,. blk 

VI: . WRITE/. WRITW .chan, .buff , .went , .blk 

V2: .WRITE/. WRITW . area, .chan, .buff , .went, .blk 
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VI: .WRITC .chan, .buff , ,wcnt,.crtn,.blk 

V2: .WRITC .area, .chan, .buff ,. went,. crtn,.blk 

VI: .WAIT .chan 
V2: .WAIT .chan 

Important features to keep in mind for Version 2 calls are: 

1. Version 2 calls require the .area argument, which points to 
the area where the other arguments will be. 

2. Enough memory space must be allocated to hold all the 
required arguments. 

3. .chan must be any legal assembler argument, not just an 
integer between 0-17 (octal) . 

4 Blank fields are permitted in the Version 2 calls. Any field 
not specified (left blank) is left alone in the argument 
block. 
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CHAPTER 10 
EXPAND UTILITY PROGRAM 



EXPAND is an RT-11 system program which processes the macro references 
in a macro assembly language source file. EXPAND accepts a subset of 
the complete macro language and, using the system library file 
SYSMAC.8K, produces an output file in which all legal macro references 
are expanded into macro- free source code. EXPAND is normally used 
with ASEMBL, the RT-11 assembler designed for minimum memory 
configurations (refer to Chapter 11) . 



10.1 LANGUAGE 

EXPAND simply copies its input files to its output file unless it 
encounters any of the following directives (see Chapter 5 for more 
information about these directives) : 



1. .MCALL 



2. .MACRO 



.name 



,ENDM 



Directs EXPAND to search the file 
SY:SYSMAC.SML to find the macro names listed 
in the .MCALL directive. If the macro names 
are found, EXPAND stores their definitions in 
its internal tables. 

Directs EXPAND to copy a macro definition 
from the user's input file into the internal 
tables. 

If .name is the name of a macro defined in 
either a .MCALL or .MACRO directive, then 
.name is expanded according to the definition 
stored for it in the EXPAND internal tables. 

If encountered while storing a macro 
definition, the .ENDM directive terminates 
the definition. It is not recognized outside 
macro definitions. 



10.2 RESTRICTIONS 

Unlike the full macro assembler (MACRO) , EXPAND only expands macros 
that observe the following restrictions: 
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1. The following directives may not be used; 



.ERROR 


.NARG 


.IF DIF 


. NCHR 


.IF IDN 


.NTYPE 


.IRP 


. PRINT 


.IRPC 


.REPT 


.MEXIT 





2. Macros cannot be nested. Recursive macros that call 
themselves directly or indirectly are illegal and cause an 
error message. 

3. Macros cannot be redefined. Once a name has been used for a 
macro name, it cannot be used again in the program for a 
macro or symbol name. 

4. Macro names must begin with a dot (.). If the dot is missing, 
an error message is printed. 

5. Dummy argument names must begin with a dot (.). Such names 
cannot be used as dummy argument names in the macro but can 
be used for other purposes outside of the macro. 

6. The backslash operator is not available. 

7. Automatically created symbols are not available. 

8. No more than 30 arguments may be used in any MACRO directive. 



10.3 CALLING AND USING EXPAND 

To run EXPAND, type: 

R EXPAND 

in response to the dot printed by the Keyboard Monitor. EXPAND 
responds with an asterisk indicating that it is ready to accept a 
command string. A command string must be of the following form: 

*of ile-if ilel , if ile 2 , . . . , if ile6 

ifile2 through ifile6 are optional. Each file specification follows 
the general RT-11 command string syntax (dev:filnam.ext) . The default 
value for each file specification is noted below: 

I/O File Dev Ext 

ofile DK PAL 

if ilel,..., device used MAC 
ifile6 for last source 
file specified 
or DK 

Type CTRL C to halt EXPAND and return control to the monitor. To 
restart EXPAND, type R EXPAND or the REENTER command in response to 
the monitor's dot. 
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EXPAND copies sequentially the specified input files to the specified 
output file until a macro directive is encountered. EXPAND then 
changes the macro directive to a comment by inserting a semicolon so 
that it will not be seen later by the assembler (usually ASEMBL) . 

If the directive is .MCALL, EXPAND searches the system library file 
(SYSMAC.8K) for the requested macro definitions. The requested 
definitions are then included in the user's program in the order in 
which they are found in the library. 

For the .MACRO directive, EXPAND reads each line following the 
directive up to the next .ENDM directive. Each line is stored in the 
internal definition table and then changed to a comment in the output 
file so that it is not processed later by the assembler. Also, any 
occurrence of a macro argument name within the definition is flagged 
internally so that it can be replaced by the real argument value 
whenever the macro is later referenced. 

For macro references, EXPAND locates the stored macro definition in 
its internal tables, binds the actual argument values to the argument 
names, and changes the macro reference to a comment line. EXPAND then 
begins copying the stored definition to the output file. Whenever a 
macro argument name is encountered in the definition, it is replaced 
by the corresponding actual argument value. 

Examples : 

The following are examples of input and corresponding EXPAND output. 

INPUT OUTPUT 



Ri'Xt 
SP»Xfc 
PC"XT 
.MACPO .CAUL ,«U»R 

js" pc».9u*& 

.ENQM 

.MCALL . L0"KIJP, ,f»EADf..V?.. 



I PT-11 MACRO EXPAND VW2-0? 

Ri"Xl 

SP»Xt> 

PC'XT 

.MACRO .CALL ,SU§R 

JSR PC.SUAW 

,£N M 

.MCALL . LOOKUP, .READ...V?.. 
.MACRO .,V2., 
...V2-1 
.ENDM 

.MACRO '.LOOKUP .AREA,. CHAN,, D*V*LK».3PF 
.IF OF ...VI 



.IF NA 


.CHAN 










MQV 


.CHAN.X0 


.ENOC 












FMT 


*O<Z0*.AREA» 


.IFF 








.IF N* 


.A»E* 










MOV 


.AREA.X0 






Move 


#1 » I f05 


.ENOC 








.IF N* 


.CHAN 










MQVB 


.CHAN, (0) 



.FNDC 
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..V2.. 

.CS6CT MAIN 
.GLOBL 3«RT 

ST»CKI .BLKW 10* 

ARFAI .BLKW 10 

BUFRI .BLKW 1001 

INBLKl .BL.KW "5 

STARTI MOV #8TACK,8P 

4, MOV Ri,-(S») 

81 ,C*IL 90"T 

.LOOKUP #INBLK,0 



r .IF NB 


.OEVBL» 


( 




J 




MOV 


.DFVBLK,?.(0) 


J.ENOC 








f.IF NB 


,3FF 






> 




MOV 


.SPF,*', £0) 


I.IFF 








1 




CL» 


«, (0) 


I.ENOC 








F 




EMT 


*OV5 


I.ENOC 








I.ENBM 








>. MACRO 


.READ 


,A»EA, , 


CHAN,, BUFF,. WCN 


>.IF OF 


...VI 






I.IF N" 


,WCNT 






1 




MQV 


,WCNT,X0 


f.ENnc 








» 




MOV 


#l,-(6.) 


1 




MOV 


.8UFF,-CtO 


I 




MQV 


,CHAN,-(fc,1 


1 




FMT 


" r O<200*.ARFA> 


I.IFF 








I.TF NB 


.AREA 






1 




MOV 


.AREA,«0 


t 




MOVB 


*8.,1C8) 


i.FNnc 








I.IF NB 


.CHAN 






1 




MQVB 


.CHAN, f0} 


I .ENOC 








f.TF NB 


,BLK 






t 




MQV 


,BLK,2'. (0) 


r.FNPic 








F.TF NB 


.BUFF 






1 




MQV 


,BUFF,«,fBl 


I.ENOC 








F.TF NB 


,WCNT 






F 




MQV 


,WCNT,ft, f01 


f.fndc 








F 




MOV 


#1,8.(0) 


F 




FMT 


*0V5 


I.FNI5C 








F.FNdM 








F 


..V2.. 






...V?«1 










.CSECT 


MAIM 






.GUOBL 


SORT 




8TACKI 


.BLKW 


100 




AREAI 


.BLKW 


10 




BUFRl 


.BLKW 


100 




INBLKI 


.BLKW 


5 




START! 


MOV #stack,sp 




Al 


MOV Rl 


,-f8P) 




BlF 


,C*LL 


SORT 






J8R PC 


,30RT 




F 


.LOOKUP #INBLK 


,0 


.IF OF 


...Vi 






.IF NB 













MQV 


0,*0 


.ENOC 












EMT 


*O<20+*INBLK> 


.IFF 








.IF NB 


#TNBLK 
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CL R Ri fBLOCK NUMBER 

.REAO #AREA»*0.#»UFR,#35fc.,Rl 



HALT 

.END START 







MOV 


*INBLK,X0 






MQVB 


#i.ic<n 


.ENOC 








.IF NB 













MOVB 


8,(0) 


.ENOC 








.IF NB 












MOV 


.«'.(«) 


.ENOC 








.IF NB 












MOV 


• fl'.CB) 


.IFF 












CLR 


«.f0) 


.ENOC 












FMT 


"0575 


.ENOC 










CLR Rl 




(BLOCK NUMBER 


1 


.READ 


#AREA,#e, 


#«UFR, #35fe,,Rl 


.IF r>r 


...VI 






.IF NB 


#*S«», 










MOV 


*2^6.,X0 


.ENOC 












MOV 


#li-f6.) 






MQV 


#BUFR,-(fe.) 






MOV 


#0,«(6.) 






FMT 


"O^G + iARFA* 


.IFF 








.IF NB 


*ARE* 










MOV 


«AREA,X0 






MOVB 


#8., 1(d) 


.ENOC 








• IF NB 


#01 










MOVB 


#0,(«) 


,ENOC 








.IF NB 


Rl 










MOV 


Rl,2.(») 


'.ENOC 








.IF NB 


#8UFR 










MOV 


#BUFR,4, (0} 


.ENOC 








.IF NB 


#?5b. 










MOV 


#2B6.,*.f0) 


.ENOC 












MOV 


*i,8.(H) 






FMT 


*0175 


.ENOC 


HALT 








.END START 
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10.4 EXPAND ERROR MESSAGES 

The following messages are caused by fatal errors detected by EXPAND. 
They print on the console terminal and cause EXPAND to restart: 



Message 



?BAD SWITCH? 



7INPUT ERROR? 



7INSUFFICIENT CORE? 



7MISSING END IN MACRO? 



?NO INPUT FILE? 



?OUTPUT DEVICE FULL? 



7WRONG NUMBER OF OUTPUT FILES? 



Explanation 

An unrecognized command 
switch was specified. 



string 



Hardware error in reading an input 
file. 

Not enough memory to store macro 
definitions. 

End of input was encountered while 
storing a macro definition; 
probably missing an .ENDM. 

There must be at least one input 
file. 

No room to continue writing output; 
try to compress the device with 
PIP. 

There must be exactly one output 
file. 



The following errors are non-fatal but indicate that something is 
wrong in the input file(s). These errors appear in the output file as 
a line in the following forms 

?*** ERROR *** message 

After each run of EXPAND, the total number of non- fatal errors is 
printed on the console terminal. 



Message 



BAD MACRO ARG 



LINE TOO LONG 



MACRO ALREADY DEFINED 
MACRO (S) NOT FOUND 

MISSING COMMA IN MACRO ARG 



Explanation 

The macro argument is not formatted 
correctly. 

A line has become longer than 132! 
characters. 

A macro was defined more than once. 

Macros listed in an .MCALL 
statement were not found in 
SYSMAC.8K (make sure SYSMAC.8K is 
present on system) . 

Found spaces or tabs within a macro 
argument when a comma was expected; 
try using brackets around the argu- 
ments, e.g., Org with spaces>. 



January 1976 
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MISSING DOT 

NAME DOESN'T MATCH 

NESTED MACROS 

NO NAME 
SYNTAX 

TOO MANY ARGS 



A macro name or argument name does 
not begin with a dot. 

Optional name given in .ENDM 
directive does not match name given 
in corresponding .MACRO directive. 

A macro is being defined or invoked 
within another macro. 



A macro definition has no name. 



A macro directive 
constructed correctly. 



is 



not 



A macro directive has more than 30 
arguments . 
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CHAPTER 11 
ASEMBL, THE 8K ASSEMBLER 

ASEMBL is designed for use on an RT-11 system with minimum memory 

space (or larger systems where system table space is critical) and is 

a subset of the RT-11 MACRO assembler described in Chapter 5. ASEMBL 
has the same features as MACRO with the following exceptions: 

1. MACRO directives (.MACRO, .MCALL, .ENDM, .IRP, etc.) are not 
recognized 

2. DATE is not printed in listings 

3. Wide line-printer output is not available 

4. There is no lower-case mode 

5. There is no enable/disable punch directive 

6. There are no floating point directives 

7. There are no local symbols or local symbol blocks 

8. CREF is not available 

Many of the macro features are supported by the EXPAND program (as 
described in Chapter 10). 



11.1 CALLING AND USING ASEMBL 

ASEMBL is loaded in response to the dot printed by the Keyboard 
Monitor with the RT-11 monitor R Command as follows: 

R ASEMBL 

followed by the RETURN key. ASEMBL responds with an asterisk (*) and 
waits for specification of the output and input files in the standard 
RT-11 format as follows: 

*object,listing=sourcel,. .. ,source6 
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where; 



object 
listing 

sourcel , 



is a binary object file output by ASEMBL. 

is the assembly listing file containing 
assembly listing and symbol table. 



the 



. . ,source6 

are the ASCII source files containing the ASEMBL 
source program(s) . A maximum of six source files 
is allowed. 

A null specification in any of the file fields signifies that the 
associated input or output file is not desired. ASEMBL file 
specifications follow the standard RT-11 convention (dev:filnam.ext) . 
The default value for each file specification is noted below: 



I/O File 


Dev 


Ext 


object 


DK 


.OBJ 


listing 


device used 

for object output 


.LST 


sourcel,. . . , 


device used for 


.PAL 


sourcen 


last source 
file specified 
or DK 





Type CTRL C to halt ASEMBL and return control to the monitor. To 
restart ASEMBL, type R ASEMBL or the REENTER command in response to 
the monitor's dot. 

Table 11-1 lists the RT-11 macro directives which are not available in 
ASEMBL. 

Table 11-1 
Directives not Available in ASEMBL 



Directive 



.MACRO 
.ENDM 
.MEXIT 
.MCALL 

.NCHR 



.NARG 



\ (backslash) 



Explanation 



Macros cannot be defined in ASEMBL. 



The number of characters in an argument cannot be 
obtained with a macro. 

The number of arguments in a macro cannot be 
obtained with a macro. 

Symbols used as macro arguments cannot be passed 
as a numeric string. 



(continued on next page) 
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Table 11-1 (Cont.) 
Directives not Available in ASEMBL 



Directive 


Explanation 


.ERROR 




Messages cannot be flagged with a P error code 
output as part of the assembly listing. Comment 
lines can be used to replace .ERROR. 


.IF IDN 
.IF DIF 


} 


Strings cannot be compared. 


.IRP 
.IRPC 


> 


Indefinite repeat blocks cannot be created. 


.NTYPE 




A macro cannot be modified based on the addressing 
mode of an argument. 


.PRINT 




Messages cannot be output as part of the assembly 
listing. Comment lines can be used to replace 
.PRINT. 


• REPT 




A block of code cannot be duplicated a number of 
times in-line with other source code using a 
directive. 


.LIST ME 


-^ 




.NLIST ME 






.LIST MEB 






.NLIST MEB 
.LIST MD 




These directives have no effect. 


.NLIST MD 






.LIST MC 






.NLIST MC 


J 




.LIST TTM 
.NLIST TTM 


y 


Terminal mode is standard and cannot be changed. 


.ENABL LC 
.DSABL LC 


> 


All lower case ASCII input is converted to 
upper case. 


.ENABL LSB 
.DSABL LSB 


> 


Local symbols and local symbol blocks are not 
available in ASEMBL. 


.ENABLE PNC 
.DSABL PNC 


> 


Binary output is always enabled. 


.ENABL FPT 
.DSABL FPT 


\ 


Floating point directives are not available. 


. FLT2 


( 




.FLT4 


J 





Example : 

This example uses the output produced by the EXPAND program as input 
to ASEMBL. The assembly listing follows. 
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.MAIN, »T»il MACRO V8«2-lfl RASE 1 



I I PT-U MACRO EXPAND V02-02 
8 

3 000001 »1 ■« 1 

4 000006 SP»X6 
9 000007 PC«XT 

6 I ".MACRO .CALL .SU»R 

7 f J3R PCi.SUBR 

8 f '.ENOM 

9 I ;,MCALL .LOOKUP, .READ, ..V?.. 

10 f, MACRO '.,V2,, 

II >.'..V2M 

12 I.FNDM 

13 », MACRO '.LOOKUP .AREA, .CHAM, .0?VBLK,.SPP 

u r.Tf or '..'.vi 

15 
lb 
17 
18 
19 
2-0 
21 
22 
23 

2a 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

01 

02 

43 

44 

45 

06 

07 

46 

09 

50 

51 

52 

53 

54 

55 

56 

57 



11-4 



I.TF NB 


.CHAN 






» 




MOV 


,CHAN,X0 


I.PNOC 








» 




FMT 


*O«20+.AREA» 


I.TPF 








I.TF N* 


.APE A 






» 




MOV 


.A»EA,X0 


t 




MOVB 


#1,1(05 


i.FNnc 








>.TF NB 


.CHAN 






t 




MOVB 


'.CHAN, (01 


r.FNnc 








f.TF NB 


'.OFVBLK 






1 




MOV 


,OPVBLK,?.f01 


r.FNDC 








».TF N* 


'.SPF 






1 




MOV 


,SPF,4.{«) 


I.TFF 








1 




TL» 


0.(05 


I.FNOC 








1 




FMT 


*0*7B 


I.FNOC 








I.PNDM 








> .MACRO 


,RFAO 


.AREA, 


. CHAN,. BUFF, '.we 


f.TF DF 


' ' VI 
. • ■ * * 






»,TF MR 


.WONT 






» 




MOV 


.WfNT.XB 


I.FNOC 








1 




MOV 


#l,-(6.) 


1 




MOV 


,BllFF,«(*..5 


1 




MOV 


.CHAN, -(6, 5 


J 




FMT 


-O«2G0*.ARFA» 


I.TFF 








I.TF NB 


.AREA 






1 




MOV 


.APEA.X0 


1 




MOVB 


#8'.,K«) 


I.FNOC 








I.TF NB 


'.CHAN 






J 




MOVB 


'.CHAN, (05 


I.FNOC 








I.TF NB 


'.BLK 






1 




MOV 


,BLK,2.(«) 


i.fnoc 









ASEMBL, the 8K Assembler 

.MAIN, RTM1 MACRO V80J-10 RASE 1* 



SB 


I.TF NB 


'.BUFF 






59 


1 




MOV 


.BUFF,4.f01 


60 


f.fNDC 








61 


I.TP NB 


'.WCNT 






62 


1 




MOV 


'.WCNT, 6. (05 


63 


I.FNOC 








64 


1 




MOV 


•1.8, {0J 


65 


t 




FMT 


"0^75 


66 


I.PNDC 








67 


1 .PNOM 








6B 


1 


..V2.. 






69 


000001 '.,',V?Bl 








70 


000000' 


".CSECT 


MAIN 




71 




.GLOBL 


SORT 




72 000910 


BT4CKI 


1BLKW 
.BLKW 


100 




73 00200 


ARFAI 


10 




74 00290 


BUPRI 


',BLKW 
.BLKW 


100 




75 00490 


IN^LKi 


5 





76 00432 012706 ST*RT| MQV #STACK,SP 

000000' 

77 00436 010146 A| MQV Rl,-.fSP) 

78 00400 Bit .CALL 8QRT 

79 00440 004767 .JSR PC, SORT 

000000G 



80 




» 


'.LOOKUP 


«INBLK 


.0 


81 




.IP of 


...VI 






82 




.IP N B 









83 








MOV 


0,*0 


84 




.ENDC 








85 








FMT 


*O«20+*INBLK» 


86 




.IPF 








87 




.IP NB 


#TN«LK 






86 00444 


012700 
000420 


> 




MOV 


*INBLK,X0 


89 004^0 


H2760 

000001 
000001 






MOVB 


«l,if0l 


90 




.ENDC 








91 




.IP NB 









92 0<*456 


H6710 

000000* 






MOVB 


0,f01 


93 




.EWOC 








94 




.IP NB 








95 








MOV 


.2'. (0) 


96 




.ENDC 








97 




.IP NB 








98 








MOV 


.«'. C0) 


99 




.IPF 








100 0462 


005060 
000004 






CLP 


«.f05 


101 




.ENDC 








10? 0466 


104375 






FMT 


*0*T5 


101 




.ENDC 








104 0470 


005001 




CLR Rl 




>BI QCK NUMBER 


105 




1 


'.REAR #AREA,#0, 


#»UPR,#?56.iRl 


106 




.IP OF 


...VI 






107 




.IP NB 


#?56. 
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.MAIN. RT-11 MACRO VS0|-1« PAGE 1* 



10S 








MOV 


#256. ,*0 


109 




'.ENDC 








110 








MOV 


#l,-(6.) 


111 








MOV 


#BUPR,-C*.J 


11? 








MOV 


#0.-(6.) 


Ill 








PMT 


*O«200+#ARPA» 


114 




'.IPF 








115 




.IP NB 


#ARPA 






116 0472 


012700 
000200* 






MOV 


#AREA,*0 


117 0476 


H2760 

000010 
000001 






MOVB 


#8'. #1(0) 


11* 




.ENDC 








119 




.ir nb 


#0 






120 0504 


H271B 

000000 






MOVB 


«0.C0) 


121 




.ENOC 








12? 




.IP NB 


Rl 






121 0510 


010160 
000002 






MOV 


Rl.2.(0) 


124 




.ENOC 








125 




,IW NB 


#PUPR 






126 0514 


012760 
000004 






MOV 


#BUFR,4,(01 


127 




.ENDC 








12S 




.ir NB 


#956. 






129 05?2 


012760 
000400 
000006 






MOV 


«256.,6.f0l 


130 




.ENDC 








131 0550 


012760 

000001 
000010 






MOV 


#1,8.(03 


132 0556 


104375 






EMT 


"om 


133 




.ENDC 








134 0540 


000000 




HALT 






135 


000432* 


I 


.END 


START 





.MAIN, RT-11 MACRO V8«8«10 
SYMBOL TABLE 



PA6E 1* 



A 000436R 
BUFR 000220R 
Rl »X000001 
STACK 000000R 



AB8. 



002 AREA 000200R 
002 INBLK 000420R 

SP a%000006 
002 START 000432R 



000000 000 
000000 001 
MAIN 000542 002 
ERRORS DETECTED! 
FREE COREI 19088. WORDS 

,LPl"TfST,PAL 



002 II 000440R 

002 PC «X000007 

SQRT ■ ****** 6 

002 '..'.V? " 0000*1 



002 
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11.2 ASEMBL ERROR MESSAGES 

The system error messages output for ASEMBL are abbreviated as 
follows : 



Abbreviation 
?BSW? 

7C0RE? 

?NIF? 
?ODF? 
?TMO? 



Explanation 

The switch specified was not recognized by the 
program. 

There are too many symbols in the program being 
assembled. Try dividing program into separately 
assembled subprograms. 

No input file was specified and there must be at 
least one input file. 



No room to continue writing output; 
compress device with PIP. 

Too many output files were specified. 



try to 
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12.1 INTRODUCTION TO RT-11 BATCH 

RT-11 BATCH is a complete job control language that allows RT-11 to 
operate unattended. RT-11 BATCH processing is ideally suited to 
frequently run production jobs, large and long running programs, and 
programs that require little or no interaction with the user. Using 
BATCH, the user can prepare his job on any RT-11 input device and 
leave it for the operator to start and run. 

RT-11 BATCH provides the ability to: 

• Execute an RT-11 BATCH stream from any legal RT-11 input 
device. 

• Output a log file to any legal RT-11 output device (except 
magtape or cassette) . 

• Execute the BATCH stream either with the Single-Job Monitor or 
in the background with a Foreground/Background Monitor. 

• Generate and support system independent BATCH language jobs. 

• Execute RT-11 monitor commands from the BATCH stream. 

RT-11 BATCH consists of two main sections: the BATCH compiler and the 
BATCH run-time handler. The BATCH compiler reads the batch input 
stream created by the user, translates it into a format suitable for 
the RT-11 BATCH run-time handler, and stores it in a file. The BATCH 
run-time handler takes the file generated by the compiler and executes 
it in conjunction with the RT-11 monitor. As each command in the 
batch stream is executed, the command, along with any terminal output 
generated by executing the command, is output to the BATCH log device. 



12.1.1 Hardware Requirements to Run BATCH 

RT-11 BATCH can be run on any Single-Job system configured with at 
least 12K words of memory. A minimum system of 16K words of memory is 
required to run BATCH in a Foreground/Background environment. A line 
printer, although optional, is highly desirable as the log device. 
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12.1.2 Software Requirements to Run BATCH 

BATCH uses certain RT-11 system programs to perform its operations. 
For example, the $BASIC command runs BASIC. SAV. The user must ensure 
that the following RT-11 programs are on the system device, with 
exactly the following names, before running BATCH. 



BASIC. SAV 
BA.SYS 
BATCH. SAV 
CREF.SAV 
FORLIB.OBJ 
FORTRA.SAV 
LINK. SAV 
MACRO. SAV 
PIP. SAV 



(BASIC users only) 



(MACRO users only) 
(FORTRAN users only) 
(FORTRAN users only) 

(MACRO users only) 



12.2 BATCH CONTROL STATEMENT FORMAT 

Input to RT-11 BATCH is either a file generated using the RT-11 Editor 
and input from any legal RT-11 input device, or punched cards input 
from the card reader. In both cases, the input consists of BATCH 
control statements. A BATCH control statement consists of three 
fields, separated from one another with spaces: command fields, 
specification fields, and comment fields. The control statement has 
the form: 



$command/ switch 



specification/switch 



! comment 



Each control statement requires a specific combination of command and 
specification fields and switches (see Section 12.4). Control 
statements may not be longer than 80 characters, excluding multiple 
spaces, tabs, and comments. A line continuation character (-) may be 
used to indicate that the control statement is continued on the next 
line (see Table 12-4) . Even if the line continuation character is 
used, the maximum control statement length is still 80 characters. 



The following example of a $FORTRAN command 
fields in a control statement. 



illustrates the various 



,$FORTRAN/LIST/RUN, PROGA/LIBRARY PROGB/EXE. 'RUN FORTRAN. 
1 — j 

command/ switches spec fields/switches comment field 



12.2.1 Command Fields 

The command field in a BATCH control statement indicates the operation 
to be performed. It consists of a command name and certain command 
field switches. The command field is indicated by a $ in the first 

tab, blank, or 



character position 
carriage return. 



and is terminated by a space, 



12.2.1.1 Command Names — The command name must appear first in a 
BATCH control statement. All BATCH command names have a dollar sign 
($) in the first position of the command, e.g., $JOB. No intervening 
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For example, 



spaces are allowed in the command name. BATCH recognizes only two 
forms of a command name: the full name and an abbreviation consisting 
of $ and the first three characters of the command name, 
the $FORTRAN command may be entered as: 

$FORTRAN 

or 
$FOR 
but cannot be entered as: 
$FORT 

or 
$FORTR 



12.2.1.2 Command Field Switches — Switches that appear in a command 
field are command qualifiers and their functions apply to the entire 
control statement. All switch names must begin with a slash (/) that 
immediately follows the command name. Table 12-1 describes the 
command field switches that are legal in BATCH and indicates the 
commands on which they can be used. Those switch characters that 
appear in braces are optional. These switches will be mentioned again 
in the sections pertaining to the commands with which they can be 
used . 

All /NO switches are the defaults, except the /WAIT switch in the 
$MOUNT and $DISMOUNT commands and the /OBJECT switch in the $LINK 
command . 



Switch 



/BAN{NER} 

/NOBAN{NER} 
/CRE{F} 

/NOCRE{F} 
/DEL{ETE} 

/NODEL{ETE} 



Table 12-1 
Command Field Switches 



Function 



Print header of job on the log file. This switch is 
allowed only on the $JOB command. 

Do not print a job header. 

Produce a cross reference listing during compilation. 
This switch is allowed only on the $MACRO command. 

Do not create a cross reference listing. 

Delete input files after the operation is complete. 
This switch is allowed on the $COPY and $PRINT 
commands. 

Do not delete input files after operation is complete. 



(continued on next page) 



12-3 



BATCH 



Table 12-1 (cont.) 
Command Field Switches 



Switch 



/DOL{LARS} 



/NODOL{LARS} 

/LIB{RARY} 

/NOLIB{RARY} 
/LIS{T} 



Function 



/NOLIS{T} 
/MAP 

/NOMAP 
/OBJ{ECT} 



/NOOBJ{ECT} 

/RT11 
/NORTH 



The data following this command may have a $ in the 
first character position of a line. This switch is 
allowed on the $CREATE, $DATA, $FORTRAN, and $MACRO 
commands. Reading of the data is terminated by one of 
the following BATCH commands: 

$JOB 

$SEQUENCE 
$EOD 
$EOJ 

or by a physical end-of-file on the BATCH input stream. 

Following data may not have a $ in the first character 
position; a $ in the first character position 
signifies a BATCH control command. 

Include the default library in the link operation. 
This switch is allowed on the $LINK and $MACRO 
commands . 

Do not include the default library in the link 
operation. 

Produce a temporary listing file (see Section 12.2.5) 
on the listing device (LST:) or write data images on 
the log device (LOG:). This switch is allowed on the 
$BASIC, $CREATE, $DATA, $FORTRAN , $JOB , and $MACRO 
commands. When used on the $JOB command, /LIST sends 
data lines in the job stream to the log device (LOG:). 

Do not produce a temporary listing file. 

Produce a temporary linkage map on the listing device 
(LST:). This switch is allowed on the $FORTRAN, $LINK, 
and $MACRO commands. 

Do not create a MAP file. 

Produce a temporary object file as output of 
compilation or assembly (see Section 12.2.5). This 
switch is allowed on the $FORTRAN, $LINK, and $MACRO 
commands. When used on $LINK, this switch means that 
temporary files are to be included in the link 
operation. 

Do not produce object file as output of compilation, 
or, on $LINK, do not include temporary files in the 
link operation. 

Set BATCH to operate in RT-11 mode (see Section 12.5). 
This switch is allowed only on the $JOB command. 

Do not set BATCH to operate in RT-11 mode. 



(continued on next page) 



12-4 



BATCH 



Table 12-1 (cont.) 
Command Field Switches 



Switch 



/NO RUN 
/TIM{E} 

/NOTIM{E} 
/UNI {QUE} 

/NOUNI{QUE} 
/WAI{T} 

/NOWAI{T} 
/WRI{TE} 

/NOWRI {TE } 



Function 



Link (if necessary) and execute programs compiled since 
the last "link-and-go" operation or start of job. This 
switch is allowed on the $BASIC, $FORTRAN, $LINK, and 
$MACRO commands. 

Do not execute or link and execute the program after 
performing the specified command. 

Write the time of day to the log file when commands are 
executed. This switch is allowed only on the $JOB 
command. 

Do not write time of day to log file. 

Check for unique spelling of switches and keynames (see 
Section 12.4.13). This switch is allowed only on the 
$ JOB command . 

Do not check for unique spelling. 

Pause to wait for operator action. This switch is 
allowed on the $DISMOUNT, $MESSAGE, and $MOUNT 
commands. 

Do not pause for operator action. 

Indicate that the operator is to WRITE-ENABLE a 
specified device or volume. This switch is allowed 
only on the $MOUNT command. 

Indicate that no writes are allowed or that the 
specified volume is read-only; the operator is 
informed and must WRITE-LOCK the appropriate device. 



12.2.2 Specification Fields 

Specification fields immediately follow command fields in a BATCH 
control statement and are used to name the devices and files involved 
in the command. These fields are separated from the command field, 
and from each other, by blanks or spaces. 

If a specification field contains more than one file to be used in the 

same operation, the + operator is used between these files. For 

example, to assemble files Fl and F2 to produce an object file F3 and 
a temporary listing file, type: 

$MACRO/LIST F1+F2/S0URCE F3/0BJECT 

If a command is to be repeated for more than one field specification, 
the "," operator is used between these files. For example, the 
following command assembles Fl to produce F2, a temporary listing 
file, and a map file F3. It then assembles F4 and F5 to produce F6 
and a temporary listing file. 

$MACRO/LIST F1/S0URCE F2/0BJECT F3/MAP ,F4+F5/SOURCE- 
F6/0BJECT 
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Note that the command field switches apply to the entire line, but the 
specification field switches apply only to the field they follow. 

Depending on the command being used, specification fields may contain 
a device specification, file specification, or an arbitrary ASCII 
string. Any of these three may be followed by an appropriate 
specification field switch (see Table 12-3) . 



12.2.2.1 Physical Device Names — Each device in an RT-11 BATCH 
specification field is referenced by means of a standard 2- or 
3-character device name. Table 2-2 in Chapter 2 lists each name and 
its related device. If no unit number is specified for devices which 
have more than one unit, unit is assumed. 

In addition to the permanent names shown in Table 2-2, devices can be 
assigned logical device names. A logical device name takes precedence 
over a physical name and thus provides device independence. With this 
feature, a program that is coded to use a specific device does not 
need to be rewritten if the device is unavailable. For example, DK: 
is normally assigned to the system device, but that name can be 
assigned to DECtape unit with an RT-11 monitor ASSIGN command. 

Certain logical names must be assigned prior to running any BATCH job 
since BATCH uses them as default devices. These devices are: 

LOG: BATCH log device (cannot be magtape or cassette) 
LST: default for listing files generated by BATCH stream 

The following are not legal device names in RT-11; if used, the 

operator must assign them as logical names with the ASSIGN command. 

These names are included here because they can be used in BATCH 
streams written for other DIGITAL systems. 



DF: 
LL: 

M7: 
M9: 
PS: 



Fixed-head disk (RF) . 

Line printer with upper and lower case 
characters . 

7-ti:ack magtape. 

9-track magtape. 

Public storage (DK: as assigned by RT-11) . 



Refer to Sections 2.7.2.4 and 12.7.1 for instructions on assigning 
logical names to devices. 
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Table 12-2 
File Name Extensions 



Extension 



.BAS 
.BAT 
.CTL 

.CTT 

• DAT 
.DIR 
.FOR 
.LST 

• LOG 
.MAC 

.MAP 
.OBJ 
.SOU 
.SAV 



Meaning 



BASIC source file (BASIC input) . 

BATCH command file. 

BATCH control file generated by the BATCH 
compiler . 

BATCH temporary file generated by the BATCH 
compiler . 

BASIC or FORTRAN data file. 

Directory listing file. 

FORTRAN IV source file (FORTRAN input) . 

Listing file. 

BATCH log file. 

MACRO or EXPAND source file (MACRO, EXPAND, SRCCOM 
input) . 

Linkage map output from $LINK operation. 

Object file, output from compilation or assembly. 

Temporary source file. 

$RUNable file or program image output from $LINK. 



12.2.2.3 Wild Card Construction — The wild card construction means 
that the file name or extension in certain BATCH control statements 
(i.e., $COPY, $CREATE, $DELETE, $DIRECTORY, $PRINT) may be replaced 
totally with an asterisk (*) . The asterisk is used as a wild card to 
designate the entire file name or extension. See Chapter 4, Section 
4.1.1, for a complete description of the wild card construction. 



12.2.2.4 Specification Field Switches — Specification field switches 
follow file specifications in a BATCH control statement and designate 
how the file will be used. These switches apply only to the field in 
which they appear. Switch names begin with a slash. The 
specification field switches legal in RT-11 BATCH are listed in Table 
12-3. Optional characters in the switch names are shown in braces. 
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Table 12-3 
Specification Field Switches 



Switch 



/BAS{IC} 
/EXECUTABLE} 

/FOR{TRAN} 

/INP{UT} 

/LIB{RARY} 

/LIS{T} 
/LOGdCAL} 

/MAC{RO} 

/MAP 

/OBJ{ECT} 

/OUT{PUT} 

/PHY{SICAL} 

/SOU{RCE} 

/VID 



Function 



BASIC source file. 

Indicates the runnable program image file to be created 
as the result of a link operation. 

FORTRAN source file. 

Input file; default if no switches are specified. 

Library file to be included in link operation (prior to 
default library) . 

Listing file. 

Indicates that the device is a logical device name; 
used in $DISMOUNT and $MOUNT commands. 

MACRO or EXPAND source file. 

Linker map file. 

Object file (output of assembly or compilation) . 

Output file. 

Indicates physical device name. 

Indicates source file. 

Volume identification. 



12.2.3 Comment Fields 

Comment fields, used to document a BATCH stream, are identified by an 
exclamation point (!) appearing anywhere except the first character 
position in the control statement. Any character following the ! and 
preceding the carriage return/line feed combination is treated as a 
comment and is ignored by the BATCH processor. For example, the 
following command: 

$RUN PIP 1DELETE FILES ON DK : 

runs the RT-11 system program PIP; the comment is ignored. 

Comments can also be included as separate comment lines by typing a $ 
in character position 1, followed immediately by the ! operator and 
the comment, e.g., 

$!DELETE FILES ON DK : 



12.2.4 BATCH Character Set 

The RT-11 BATCH character set is limited to the 64 upper-case 
characters (i.e., ASCII 40 through 137). The current ASCII set is 
assumed (i.e., character 137 is underscore and not left arrow, and 
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character 136 is circumflex, not up-arrow). No control characters 
other than tab, carriage return, and line feed are supported by the 
BATCH job control language. 

Table 12-4 details the way in which BATCH normally interprets certain 
characters. Character interpretations are different when RT-11 mode 
is used (see Section 12.5). 



Table 12-4 
Character Interpretation 



Character 



Interpretation 



blank/space 



0-9 



A-Z 



Specification field delimiter. Separates arguments in 
control statements. Any string of consecutive spaces 
and tabs (except in quoted strings) is considered a 
blank and is equivalent to a single space. 

Comment delimiter. All characters after the 
exclamation point are ignored by the input routine, up 
to the carriage return/line feed. 

Used to pass a text string containing delimiting 

characters where the normal precedence rules would 

create the wrong action, e.g., to include a space in a 
volume identification (/VID) . 

BATCH control statement recognition character. A 
dollar sign ($) in the first character position of a 
BATCH input stream line indicates that the line is a 
control statement. 

Delimiter for file extension (type) . 

Indicates line continuation if the character after the 
hyphen is one of the following: 

• a carriage return/line feed 

• any number of spaces followed by a carriage 
return/line feed 

• a comment delimiter (!) 

• spaces followed by a comment delimiter (!) 

If any other character follows the hyphen, the hyphen 
is assumed to be a minus sign indicating a negative 
value in a switch. 

Start of a switch name. Must be followed immediately 
by an alphanumeric string. 

Numeric string components. 

Immediately follows a device name. Also can be used to 

separate a switch name from its value or to separate a 

switch value from its subvalue (: can be used 
interchangeably with = for this) . 

Alphabetic string components. 



(continued on next page) 



12-9 



BATCH 



Character 



Table 12-4 (cont.) 
Character Interpretation 



Interpretation 



CR/LF 



Separates switch name from value. 

Illegal character except when preceding a directive 
to the BATCH run-time handler from the operator. 
(To include \ in an RT-11 mode command, use \s, .) 

Delimiter separating multiple files in a single 
specification field. Also used to indicate a positive 
value in switches. 

The comma (,) is used to separate sets of arguments for 
which the command is to be repeated. 

The * is used as a wild card in utility command file 
specifications . 

Carriage return/line feed. Indicates end-of-line (or 
end of logical record) for records in the BATCH input 
stream. 



12.2.5 Temporary Files 

When field specifications are not included in a BATCH command line, 
BATCH sometimes generates temporary files. For example, a $FORTRAN 
command which is followed in the BATCH stream by the FORTRAN source 
program could be entered as: 

$FORTRAN/RUN/OBJECT/LIST 

FORTRAN source program 
$EOD 

This command generates a temporary source file from the source 
statements that follow, a temporary object file, a temporary listing 
file, and a temporary save image file. 

BATCH sends temporary files to the default device (DK:) or the listing 
device (LST:) according to their nature. If the device is 
file-structured, BATCH assigns file names and extensions as follows: 



nnnmmm.LST 
nnnmmm.MAP 
nnnppp.OBJ 
nnnppp.SAV 
nnnppp.SOU 
where : 

nnn 



for temporary listing files (sent to LST:) 

for temporary map files (sent to LST:) 

for temporary object files (sent to DK:) 

for temporary save image files (sent to DK:) 

for temporary source files (sent to DK:) 



is the last three digits of the sequence number 
assigned to the job by the $SEQUENCE command (see 
Section 12.4.22). Thus, a sequence number of 12345 
produces a file name beginning 345. If no $SEQUENCE 
command is used, nnn is set to 000. 



January 1976 
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is the mth listing (or map) file since the BATCH 
run-time handler (BA.SYS) was loaded. The first such 
file, listing or map, is 000. Each time a new 
temporary file is generated, the file name is 
incremented by 1. Thus, the second listing file 
produced under job sequence number 12345 is 
345001. LST, and the first map file produced is 
345000. MAP. 



PPP 



is the pth object, save image, or source file in the 
current BATCH run. The first such file (object, save 
image, or source) is 000. Each time a new temporary 
file is generated, the file name is incremented by 1. 
These file names are reset to 000 every time that 
BATCH is run and after every $LINK, $MACRO, or 
$F0RTRAN command that uses the temporaries. 



12.3 General Rules and Conventions 



The following general rules and conventions are associated with 
BATCH processing. 



RT-11 



1. A dollar sign ($) is always in the first character position 
of a command line. 

2. Each job must have a $JOB and $EOJ command (or card). 

3. Command and switch names can be spelled out entirely or the 
first three characters of the command and required characters 
of the switch can be specified. 

4. Wild card construction (*) can be specified only for the 
utility commands: $COPY, $CREATE, $DELETE, $DIRECTORY, and 
$PRINT. 

5. Comments can be included at the end of command lines or in a 
separate comment line. When comments are included in a 
command line, they must follow the command and be preceded by 
an exclamation mark. 

6. Only 80 characters per control statement (card record) are 
allowed, excluding multiple spaces, tabs, and comments. 

7. When file specifications are omitted from BATCH commands and 
data is supplied in the BATCH stream, the system creates a 
temporary file with a default name (see Section 12.2.5). 

8. The RT-11 monitor type-ahead feature is restricted to BATCH 
handler directives (see Section 12.7.3) to be inserted into a 
BATCH program. No other terminal input (except to the 
foreground) can be entered while a BATCH stream is executing. 
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12.4 BATCH COMMANDS 



BATCH commands are placed in the input stream to indicate to the 
system which functions to perform in the job. All BATCH commands have 
a dollar sign ($) in the first character position of the command, 
e.g., $JOB. Intervening spaces are not allowed in command names. The 
command name must always start in the first character position of the 
line (card column 1) . 

BATCH commands are presented in alphabetical order in this chapter for 
ease of reference. However, a user who is unfamiliar with BATCH may 
prefer to read the commands in a functional order as detailed in Table 
12-5. The characters shown in braces are optional. 



Table 12-5 
BATCH Commands 



Command 



$SEQ{UENCE} 

$JOB 
$EOJ 
$MOU{NT> 

$DIS{MOUNT} 

$FOR{TRAN} 
$BAS{IC} 
$MAC{RO} 
$LIB{RARY} 

$LIN{K} 

$RUN 

$CAL{L} 

$CHA{IN} 
$DAT{A} 
$EOD 
$MES{SAGE} 



Section 



12.4.22 

12.4.13 
12.4.11 
12.4.18 

12.4.9 

12.4.12 
12.4.1 
12.4.16 
12.4.14 

12.4.15 

12.4.21 
12.4.2 

12.4.3 
12.4.6 
12.4.10 
12.4.17 



Function 



Assigns an arbitrary identification number 
to a job. 

Indicates the start of a job. 

Indicates the end of a job. 

Signals the operator to mount a volume on a 
device and optionally assigns a logical 
device name. 

Signals the operator to dismount a volume 
from a device and deassigns a logical device 

name . 

Compiles a FORTRAN source program. 

Compiles a BASIC source program. 

Assembles a MACRO source program. 

Specifies libraries that are to be used in 
linkage operations. 

Links modules for execution. 

Causes a program to execute. 

Transfers control to another BATCH file, 
executes that BATCH file, and returns to the 
calling BATCH stream. 

Passes control to another BATCH file. 

Indicates the start of data. 

Indicates the end of data. 

Issues a message to the operator. 



(continued on next page) 
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Command 



Table 12-5 (cont.) 
BATCH Commands 



$COP{Y} 
$CRE{ATE> 

$DEL{ETE} 
$DIR{ECTORY} 

$PRI{NT} 
$RT1{1} 



Section 



12.4.4 
12.4.5 

12.4.7 

12.4.8 

12.4.19 
12.4.20 



Function 



Copies files. 

Creates new files from data included in 
BATCH stream. 

Deletes files. 

Provides a directory of the specified 
device. 

Prints files. 

Specifies that the following lines are RT-11 
mode commands. 




12.4.1 $BASIC Command 

The $BASIC command calls RT-11 Single-User BASIC to execute a BASIC 
source program. The $BASIC command has the following format: 



$BASIC{/switch} {dev:filnam.ext/sw} {'comments} 



where: 



/switch indicates the switches that can be appended to the 
$BASIC command. The switches are as follows: 

/RUN indicates that the source program is to 

be executed. 
/NORUN indicates that the program is to be 

compiled only; error messages are sent 

to the log file. 
/LIST writes data images that are contained in 

the job stream to the log file (LOG:). 
/NOLIST writes data images to the log file only 

if $JOB/LIST was specified. 

dev: f ilnam.ext 

indicates the name of the source file and the device 
on which it resides. If dev: is omitted, DK: is 
assumed. If ext is omitted, the extension .BAS is 
assumed. If this specification is omitted, the 
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/sw 



source statements must immediately follow the 
command in the input stream. 



$BASIC 



The source program included after a $BASIC statement 
can be terminated either by a $EOD command or by any 
other BATCH command that starts with a $ in the first 
position. 

indicates the switches that may follow the source 
file name. Any file name with no switch appended is 
assumed to be the name of a source file. This switch 
can have one of the following values or can be 
omitted . 

/BASIC indicates that the file name specified 

is a BASIC source program. 
/SOURCE performs the same function as /BASIC. 
/INPUT performs the same function as /BASIC. 

The $BASIC command can be followed by the source program, by legal 
BASIC commands such as RUN, and by data. The following two BATCH 
streams, for example, produce the same results. 



SBflSIC 
16 INPUT 
28 PRINT 
30 END 
RUN 
12.3 
*E0D 



*BflSIC/RUN 
10 INPUT fl 

29 PRINT fl 

30 END 
*DflTfi 
123 
*E0D 




12.4.2 $CALL Command 

The $CALL command transfers control to another BATCH control file, 
temporarily suspending execution of the current control file. The 
CALLed file is executed until $EOJ is reached or until the job aborts; 
control then returns to the statement following the $CALL in the 
originating BATCH control file. Calls can be nested up to 31 levels. 
The log file for the CALLed BATCH file is included in the log file for 
the originating BATCH program. 

The format of the $CALL command is : 

$CALL dev:f ilnam.ext {icomments} 

No switches are allowed in the $CALL command. $JOB command switches 
are saved across a $CALL but do not apply to the called BATCH file. 
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If .CTL is specified as the file extension, a precompiled BATCH 
control fUe is assumed. if no .ext is specified, .BAT is assumed, 
and the called BATCH stream is compiled before execution. 

Please note that if the program called generates temporary files, 
tnose files may supersede currently existing temporary files if the 
two jobs have the same sequence number. For example, consider the 
following two BATCH streams: 

* FOR /OB J fl * FOR, 'OB J fl 

* FOR/OBJ B *CRLL C 

*L INK/RUN *F0R/OBJ B 

*L INK/RUN 



ng: 



The called BATCH file (C.BAT) contains the follow! 

*JOB 

*F0R/0BJ fll 
*FQR/0BJ Bl 
*L INK/RUN 

*e:oj 

The temporary object files generated by C.BAT would change the 
behavior of the above two BATCH statement sequences since the first 
temporary file created by C.BAT (000000. OBJ) would supercede the 
temporary file produced by the first $FORTRAN command (000000 .OBJ) . 
This could be prevented by giving the BATCH job C.BAT a unique 
sequence number (see Section 12.4.22). 




12.4.3 $CHAIN Command 

The SCHAIN command transfers control to a named BATCH control file but 
does not return to the input stream which executed the $CHAIN command. 
The format of the $CHAIN command is: 

$CHAIN dev:filnam.ext {'comments} 

No switches are allowed in the $CHAIN command. If .CTL is specified 
as the file extension, a precompiled BATCH control file is assumed. 
If no .ext is specified, .BAT is assumed, and the chained BATCH stream 
is compiled before execution. 

An $EOJ command should always follow the $CHAIN command in the BATCH 
stream. 
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NOTE 

The values of BATCH run-time variables 
remain constant across a $CALL, $CHAIN, 
or return from call. See Section 
12.5.2.2 for a description of these 
var iables . 

The $CHAIN command is useful for transferring control to programs that 
need only be run once at the end of a BATCH stream. For example, the 
following BATCH program (PRINT.BAT) could be used to print and then 
delete all temporary listing files generated during the current BATCH 
job. 

$J0B IPRINT ALL LIST FILES 

*PR1NT/DELKTE *. LST 

*E0J 

PRINT.BAT can then be run with the $CHAIN command, e.g., 

*J0B 

*MFICRG/RUN/LIST F1LE1, FILE2, FILES 

SCHRIN PRINT 

*EQJ 




12.4.4 $COPY Command 

The $COPY command copies files in image mode from one device to 
another. The wild card construction (see Section 12.2.2.3) can be 
used in the input and output file specifications. More than one input 
file can be concatenated to form one output file so long as the output 
specification does not contain a wild card. The $COPY command has the 
following format. 

$COPY{/switch} dev:filnam.ext/OUTPUT dev: f ilnaml.ext{/INPUT}- 
{ Icomments} 



where i 



/switch indicates switches that can be appended to the $COPY 
command . 

/DELETE indicates that input files are to be 
deleted after the copy operation. 

/NODELETE indicates that input files are not to be 
deleted after the copy operation. 
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dev: 



f ilnam 

ext 

/OUTPUT 
f ilnaml 



/INPUT 



indicates the device containing the files to be 

copied for the input portion of the command or the 

device to which the files are to be copied for the 

output portion of the command. If dev: is not 
specified, DK: is assumed. 

indicates the name to be assigned to the output file; 
a wild card may be used instead of an explicit file 
name. Additional output files can be specified if 
they are separated from each other with commas. 

indicates the file extension and must be specified. 
For input files, a wild card can be used instead of 
an explicit extension. For output files, wild cards 
can be used so long as no concatenation is specified. 

is appended to a file specification to indicate that 
it is for the output file. 

specifies the name of the input file. Wild cards can 
be used instead of an explicit file name. Additional 
input files can be specified if they are separated 
from each other with commas. Files are copied to the 
output file in the order specified. 

is appended to the input file specif ier (s) . The 
system assumes input if no switch is used. 



The following are examples of the SCOPY command: 

SCO P V * . B H S / U T P LI T T 1 : * . B Pi S 

The above command copies all files with the extension 
DECtape on unit 1 to the default storage device DK. 

*C0PV FILE2. FOR/OUTPUT F1LEB. FOR+FILEt. FOR 



,BAS from the 



The above command merges the input files FILEO.FOR and FILE1.F0R to 
form one file called FILE2.F0R and stores FILE2.F0R on device DK. 

SCOPY FILE'S. FOR + F ILO. FOR/OUTPUT' F II E0. F'OR + FU El. FOR 

The above command copies. FILEO.FOR to DK: as FILE2.FOR and FILE1.FOR 
as FILE3.F0R. 

* C P V * . * ,•' U T D T 8 : * . F R, 'J T 1 ■ * . * / U 7' C- T 6 : * . * 

The above command copies all files with the extension .FOR from DTO: 
to DK: and all files on DTO: to DTI:. 
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12.4.5 $CREATE Command 

The $CREATE command generates a file consisting of data records from 
data that follows the $CREATE command in the input stream. An error: 
occurs if the data does not immediately follow the $CREATE command. A 
$DATA command must not precede the data records. 

The data associated with $CREATE can be followed by a $EOD command to 
signify the end of data or any other BATCH control statement can be 
used to indicate end of data and initiate a new function. The $CREATE 
command has the following format: 

$CREATE {/switch} dev : f ilnam. ext {"comments} 



where : 

/switch 



indicates switches that can be appended to the 
$CREATE command. 



/DOLLARS 

/NODOLLARS 

/LIST 
/NOLIST 



indicates that the data following this 
command may have a $ in the first 
character position of a line, 
indicates that a $ may not be in the 
first character position of a line, 
writes data image lines to log file, 
does not write data image lines to log 
file. If $JOB/LIST was specified, this 
switch is ignored. 



dev: 



f ilnam 



device on which the file 
specified. 



is to reside; DK: if not 



indicates the name to be assigned to the 
file name must be specified. 



file. 



ext 



indicates the file extension. If extension 
omitted, f ilnam must be followed by a period. 



The 



is 



The following is an example of the $CREATE command: 

*CREflTE,'LIST PROG. FOR 
FORTRAN source file 



*E0D 

The data records following the $CREATE command become a new file 
(PROG. FOR) on the default device (DK:) and a listing is generated on 
logical device LOG:. 
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12.4.6 $DATA Command 

The $DATA command is used to include data records in the input stream. 
No file name is associated with the data; the data is transferred to 
the appropriate program as though input from the console terminal. 
For example, the $RUN command for a particular program can be followed 
by a $DATA command and the data records to be processed by the 
program. The data records must be valid data for the program that is 
to use them. 

The $DATA command has the following format; 

$DATA{/switch} {Icomments} 

Four switches can be used with the $DATA command. 

/DOLLARS indicates that the data following this command may 
have a $ in the first character position of a line. 

/NODOLLARS indicates that a $ may not be in the first character 
position of a line. 

/LIST writes data image lines to the log file. 

/NOLIST does not write data images to the log file. If 
$JOB/LIST was specified, this switch is ignored. 

An $EOD command normally follows the last data record. However, any 
other BATCH command may also signal the end of the data so long as 
$DATA/DOLLARS is not specified (see Table 12-1). 

The following example shows data being entered into a BASIC program 
(TEST1.BAS). 

*BRS2C/RUN Tt:S"! J. BfiS 

*DRTC 

25, ?5, 12b, 146 

1 8 , 2 1 6 , 5 2 .. 8 ? 4 

$E0D 
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12.4.7 $DELETE Command 

The $DELETE command is used to delete files from the specified device. 
This command has the form: 

$DELETE dev: f ilnaml .ext{ ,dev:f ilnam2 . ext , . . . ,dev: f ilnamn.ext }- 
{ [comments} 

where filnaml through filnamn are the names of the files to be 
deleted. The file name and extension are required. Wild cards can be 
used in the file name and extension positions. 

The following example deletes all files named TESTl on the default 
device (DK: ) . 

*DELETE TESTl. * 

The following example d,eletes all files with .FOR extensions on DTI : 
then deletes all files with .MAC extensions on DK:. 

^DELETE DTI:*. FOR, *. MAC 



$ DIRECTORY 



12.4.8 $DIRECTORY Command 

The $DIRECTORY command outputs a directory of the specified device to 
a listing file. If no listing file is specified, the listing goes to 
the BATCH log file. Wild cards can be used in the specification 
fields. This command has the form: 

$DIRECTORY {dev : f ilnam . ext/LIST } {dev: f ilnam.ext }{/INPUT}- 
{ ! comments} 
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where : 



/LIST 



indicates name of directory listing file. 



/INPUT indicates input files to be included in directory 
(default) . 

The following are examples of the $DIRECTOR¥ command: 

*DIRECTORV 

The above command outputs a directory of the device DK: to the BATCH 
log file. 

3 DIRECTORS' FOR. DIR/L 1ST + . FOR 

The above command creates a directory file (FOR.DIR) on the device 
DKs. The directory contains the names, lengths, and dates of creation 
of all FORTRAN source files on the device DK:. 



^DISMOUNT 



12.4.9 $DISMOUNT Command 

The $DISMOUNT command removes the logical device name assigned by a 
$MOUNT command. When $DISMOUNT is encountered during the execution of 
a job, the entire $DISMOUNT command line is printed on the console 
terminal to inform the operator of the specific device to unload. 
This command has the form: 

$DISMOUNT{/switch} ldnj {/LOGICAL } {Icomments} 

where: 



/switch indicates the switches that can be 
$DISMOUNT command. 



appended to the 



/WAIT 



/NO WAIT 



indicates that the job is to pause until 
the operator enters a response. If 
neither /WAIT nor /NOWAIT is specified, 
/WAIT is assumed. BATCH rings a bell at 
the terminal, prints the physical device 
name to be dismounted and a ?, and waits 
for a response. (Input to the BATCH 
handler can be entered, see Section 
12.7.3.) 

does not pause for operator response. 
BATCH prints the physical device name to 
be dismounted. 
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ldn: is the logical device name to be deassigned from the 
physical device. 

/LOGICAL identifies the device specification as a logical 
device name. 

The following example instructs the operator to dismount the physical 
device with the logical device name OUT and removes the logical 
assignment of device OUT. In, this case, OUT is DTO. The operator 
dismounts DTO and types a carriage return. 

*D I SMOUNTYWR I T OUT : /LOG I CfiL 
DTG? 




12.4.10 $EOD Command 

The $EOD command indicates the end of data record or the end of a 
source program in the job stream. The format of this command is: 

$EOD {'comments} 

The $EOD command can signal the end of data associated with any of the 
following commands: 

$BASIC 

$CREATE 

$DATA 

$ FORTRAN 

$ MACRO 

The $EOD command in the following example indicates the end of a 
source program that is to be compiled, linked, and executed. 

*t-"0RTRfiN/RUN 

source program 

*E0D 
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12.4.11 $EOJ Command 

The $EOJ command indicates the end of a job. This command must be the 
last statement in every BATCH job. The command has the following 
format: 

$EOJ Ocomments} 

If a $JOB command, a $SEQUENCE command, or a physical end-of-file is 
encountered in the input stream before $EOJ, the error message NO $EOJ 
appears in the log file. 



$FORTRAN 



12.4.12 $ FORTRAN Command 

The $FORTRAN command calls the FORTRAN compiler to compile a source 
program. Optionally, this command can provide printed listings or 
list files and may produce a linkage map in the listing. The $FORTRAN 
command has the following format: 

$FORTRAN {/switch } {dev: f ilnaml . ext/sw } {dev: f ilnam2 . ext/OBJECT }- 
{dev : f ilnam3 . ext/LIST } {dev : f ilnam4 . ext/EXECUTE }- 
{dev:f ilnam5.ext/MAP } {dev: f ilnam6.ext/LIBRARY } {'comments} 



where : 



/switch indicates the switches that can be appended to the 
$FORTRAN command. The switches are as follows: 



/RUN 



indicates that the source program is to 
be compiled, linked with the default 
library (initially FORLIB.OBJ, may be 
reset with the $LIBRARY command) , and 
executed . 
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/NORUN indicates that the program 

compiled only. 
/OBJECT indicates that a temporary 

is to be produced. 
/NOOBJECT indicates that a temporary 

is not to be produced. 
/LIST indicates that a list file 

produced on the listing devi 
/NOLIST indicates that a list file i 

produced . 
/MAP produces a linkage map on 

device (LST: ) . 
/NOMAP does not create MAP file. 
/DOLLARS indicates that the data fol 

command may have a $ in 

character position of a line 
/NODOLLARS indicates that a $ may not 

first character position of 



is to be 

object file 

object file 

is to be 
ce (LST:). 
s not to be 

the listing 



lowing this 
the first 

be in the 
a line. 



devrfilnaml.ext 

indicates the device, file name, and extension of the 
FORTRAN source file. If filnaml is not specified, 
the $FORTRAN source statements must immediately 
follow the $FORTRAN command in the input stream; 
BATCH generates a ' temporary source file that is 
deleted after it is compiled (see Section 12.2.5). 



/sw 



The source program included after a $FORTRAN 
statement can be terminated either by a $EOD command 
or by any other BATCH command so long as 
$FORTRAN/DOLLARS is not specified (see Table 12-1). 
A BATCH command is one that starts with a $ in the 
first position. 

can have one of the following values or can be 
omitted: 



/FORTRAN 



/SOURCE 
/INPUT 



indicates that the file name specified 
is a FORTRAN source program. Any file 
name with no switch appended is assumed 
to be the name of a source file, 
performs the same function as /FORTRAN, 
performs the same function as /FORTRAN. 



dev : f ilnam2 . ext/OBJECT 

indicates the device, file name, and extension of the 
object file produced by compilation. The object file 
remains on the specified device after the job 
finishes. The object file specification, if 
included, must be followed by the /OBJECT switch. 

If the object file specification is omitted but 

$FORTRAN/OBJECT is specified, a temporary object file 

is created, included in any $LINK operations that 

follow it in the job, and deleted after the link 
operation. 

dev : f ilnam3 . ext/LIST 

indicates the name to be assigned to the list file 
created by the compiler. The list file is not 
printed automatically if LST: is assigned to a 
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file-structured device, but it can be listed using 
the $PRINT command. The list file specification must 
be followed by the /LIST switch. 

dev : f ilnam4 . ext/EXECUTE 

indicates the name to be assigned to a save image 
file. The save image file specification must be 
followed by the /EXECUTE switch. If this field is 
not included, BATCH generates a temporary save image 
file (see Section 12.2.5) and then deletes the 
temporary file. 

dev: f ilnam5.ext/MAP 

indicates the name to be assigned to the linkage map 
file created by the Linker. The map specification 
must be followed by the /MAP switch. 

dev : f ilnam6 . ext/LIBRARY 

indicates that the specified file is to be included 
in the link procedure as a library before FORLIB.OBJ. 
The file must be a library file (produced by RT-11 
LIBR) . The library specification must be followed by 
the /LIBRARY switch. 

The following are examples of ^FORTRAN commands: 

<*FORTRRN/RUN PROGft. FOR: 

The above command calls FORTRAN to compile a source program named 
PROGA.FOR. The program is compiled and executed. 

SFORTRfirVNOOBJ/LIST 
source program 

*E0D 

The above command sequence compiles the FORTRAN program but does not 
produce an object file. A temporary listing file is created on LST: . 




12.4.13 $JOB Command 

The $JOB command indicates the beginning of a job. Each job must have 
its own $JOB command. This command has the following format: 

$J0B{/switch}{/switch2}{/switchn} { ! comments} 
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The switches allowed in the $JOB command are: 

/BANNER print header (a repetition of the $JOB command) on 
the log file, 

/NOBANNER do not print job header. 

/LIST write data image lines that are contained in the job 
stream to the log file. 

/NOLIST write data image lines to the log file only when a 
/LIST switch exists on a $BASIC, $CREATE, or $DATA 
command that has data lines following it. 

/RT11 if no $ appears in column 1 when one is expected, 
assume that the line or card is an RT-11 mode command 
(see Section 12.5) . 

/NORTH do not process RT-11 mode commands. 

/TIME write the time of day to the log file when command 
lines are executed (see NOTE on following page) . 

/NOTIME do not write time of day. 

/UNIQUE check for unique spelling of switches and keynames. 
When this switch is used, commands and switches may 
be abbreviated to the least number of characters that 
still make their names unique. For example, the 
/DOLLARS switch can be abbreviated to /DO since no 
other switches begin with the characters DO. 

/NOUNIQUE check only for normal switch and keyname spellings. 

Each job must be ended with a $EOJ command if it is to be run. If an 
input stream consists of more than one job, BATCH automatically 
terminates one job when the $JOB command for the next job is 
encountered. A job terminated with another $JOB command will never be 
run; an error message (NO $EOJ) will appear in the log. 

The following $JOB command specifies that the time of day be written 
to the log file before each BATCH command beginning with a $ is 
executed and that unique abbreviations of BATCH commands and switches 
be accepted. 

* J OB /'TIME /UN I QUE 



January 1976 
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NOTE 

If the /TIME switch is used on the $JOB 
command, the $DATA command cannot be 
used. For example, this job will not 
run properly: 

$ JOB/TIME 
*RUN PROG 
Mi AT A 
IS 3 
$EOD 

«;:cu 

The /TIME switch uses the KMON TIME com- 
mand to print the current time on the log 
for each BATCH command, including $DATA, 
causing an abort of the program that was 
to use the data. To avoid the problem, 
use RT-11 mode: 

$ JOB/ TIME 
*RTl:l. 
,R PROG 
#123 
$EOJ 
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12.4.14 $LIBRARY Command 

The $LIBRARY command allows the user to specify a list of library 
files that will be included in FORTRAN links or with other linkage 
operations that specify the /LIBRARY switch. By default, the list of 
libraries contains only FORLIB.OBJ, the RT-11 FORTRAN library. This 
command has the form: 

$LIBRARY mylib {Icomments} 

or 

$LIBRARY mylib+FORLIB {'comments} 

where: 

FORLIB is the RT-11 FORTRAN library and mylib is a user library. 
Libraries are linked in order of their appearance in the $LIBRARY 
command . 

The following example shows two user libraries (LIBl.OBJ and LIB2.0BJ) 
to be included in FORTRAN links before FORLIB.OBJ. 

^LIBRARY LIB1. 0BJ+LIB2. OBJ+FORL I B. OBJ 




12.4.15 $LINK Command 

The $LINK command is used to produce save image files from object 

files. This command links the specified files (if any) with all 

temporary object files created since the last link or "link-and-go" 
operation (if any). 
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Temporary object files are those created as a result of a $FORTRAN 01: 
$MACRO command in which object files were neither specifically named 
by using the /OBJECT switch nor suppressed by using the /NOOBJECT 
switch. Permanent object files are created by using the /OBJECT 
switch on a $FORTRAN or $MACRO file descriptor. 

Files are linked in the following order: 

1. First, temporary files are linked in the order in which they 
were compiled. 

2. Then, permanent files are linked in the order in which they 
are specified in the $LINK command. 

3. If a library is specified in the $LINK command, it is linked 
next, providing that unresolved references remain. 

4. If $LINK/LIBRARY is specified, the default library list is 
searched and linked. 

The format for this command is: 

$LINK{/switch} {filnaml.ext/OBJECT} {f ilnam2 .ext/LIBRARY}- 
{f ilnam3 .ext/MAP} {f ilnam4.ext/EXECUTE } {"comments} 

where: 



/switch indicates the switches that can be appended 
$LINK command. The switches are as follows: 



to the 



/LIBRARY indicates that the FORTRAN library 
(FORLIB.OBJ) and any default libraries 
specified in the $LIBRARY command are to 
be included in this $LINK operation. 
This switch is normally used when the 
files being linked do not include any 
temporary FORTRAN object files or when 
$FORTRAN was specified without the /RUM 
or /MAP switch but the default library 
list is to be searched for unresolved 
references . 

/NOLIBRARY Indicates that the default libraries are 
not to be included. 

/MAP produces a temporary 
listing device (LST:) 

/NOMAP indicates that a map file 
produced . 

/OBJECT indicates that temporary 
are to be included in 
neither /OBJECT nor 
specified, $LINK/OBJECT is assumed 

/NOOBJECT indicates that temporary files are 
to be included in the link. 

/RUN indicates that the save image files 
associated with this $LINK command are 
to be executed when the link is 
complete. 

/NORUN indicates that program linking only is 
to occur. 



load map on 



is not to 



the 
be 



object files 

the link. If 

/NOOBJECT is 



not 
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f ilnaml .ext/OBJECT 

indicates the name of the object file to be linked. 
If /OBJECT is not specified, it is assumed as the 
default. 

f ilnam2 .ext/LIBRARY 

indicates that the specified file is to be included 
in the link procedure as a library. The file 
specified must be a library file (produced by RT-11 
LIBR) . 

f ilnam3.ext/MAP 

indicates the load map file to be created as a result 
of the $LINK command. 

f il nam4 . ex t/EXECUTE 

indicates the save image file to be created as a 
result of the $LINK command. 

The following are examples of the $LINK command: 

*L INK /RUN 

The above command links all temporary object files created since the 
last $LINK command or the last $FORTRAN/OBJ or $MACRO/OBJ command. 

SLINK/MRP PR0Q1. 0BJ+PR0G2. OBJ PROQR. SflV/EXE 

The above command links the temporary files and the object files 
PROGl.OBJ and PROG2.0BJ to form a save image file named PROGA.SAV. It 
also creates and outputs a temporary map file. 



$MACRO 



12.4.16 $MACRO Command 

The $MACRO command calls the MACRO assembler to assemble a source 
program and, optionally, to provide printed listings or list files. 
MACRO listing directives, if any, must be specified in the source 
program to enable their use, as they cannot be entered at BATCH 
command level. 

The $MACRO command has the following format: 

$MACRO{/switch} {filnaml.ext/sw} {f ilnam2.ext/0BJECT}- 
{filnam3.ext/LIST} {f ilnam4.ext/MAP} {filnamS. ext/LIBRARY }- 
{filnam6.ext/EXECUTE} {Icomments} 

where : 



12-29 



BATCH 



/switch 



/sw 



indicates the switches that can be appended to the 
$MACRO command. The switches are as follows: 



/RUN 

/NORUN 

/OBJECT 

/NOOBJECT 

/LIST 

/NOLIST 

/CREF 

/NOCREF 

/MAP 

/NOMAP 
/DOLLARS 

/NODOLLARS 

/LIBRARY 

/NOLIBRARY 



indicates that 
be assembled, 1 
indicates that 
be assembled on 
indicates that 
is to be produc 
indicates that 
is not to be pr 
indicates that 
produced on the 
indicates that 
produced . 
specifies that 
is to be produc 
indicates that 
is not to be pr 
produces a link 
listing file on 
does not create 
indicates that 
command may h 
character posit 
indicates that 
first character 
indicates that 
be included in 
indicates that 
not to be 
operation. 



the source program is to 

inked, and run. 

the source program is to 

iy. 

a temporary object file 

ed. 

a temporary object file 

oduced . 

a listing file is to be 

listing device (LST:). 
a list file is not to be 

a cross reference listing 
ed during assembly, 
a cross reference listing 
oduced during assembly, 
age map as part of the 

LST: . 

MAP file, 
the data following this 
ave a $ in the first 
ion of a line, 
a $ may not be in the 

position of a line, 
the default library is to 
the link operation, 
the default library is 

included in the link 



f ilnaml .ext 



indicates the name of the source file in the format 
dev: f ilnam.ext . If filnaml is not specified, the 
$MACRO source statements must immediately follow the 
$MACRO command in the input stream. 

The source program included after a $MACRO statement 
can be terminated either by a $EOD command or by any 
other BATCH command so long as $MACRO/DOLLARS is not 
specified. A BATCH command is one that starts with a 
$ in the first position. 

can have one of the following values or can be 
omitted: 



/MACRO 



/SOURCE 
/INPUT 



indicates that the file name specified 
is a MACRO source program. Any file 
name with no switch appended is assumed 
to be the name of a source file, 
performs the same function as /MACRO, 
performs the same function as /MACRO. 



f ilnam2 . ext/OBJECT 

indicates the name (in the format dev: f ilnam.ext) to 

be assigned to the object file produced by 

compilation. 

The object file remains on the specified device after 

the job finishes. The object file specification, if 

included, must be followed by the /OBJECT switch. 
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If the object file specification is omitted but 
$MACRO/OBJECT is specified, a temporary object file 
is created, included in any $LINK operations that 
follow the $MACRO command in the job, and deleted 
after the link operation (see Section 12.2.5). 

filnam3.ext/LIST 

indicates the name to be assigned to the list file 
created by the assembler. The list file is not 
printed automatically if LST: is assigned to a 
file-structured device, but can be listed using the 
$PRINT command. The list file specification must be 
followed by the /LIST switch. 

f ilnam4.ext/MAP 

indicates the file to which the storage map is to be 
output. 

filnam5.ext/LIBRARY 

indicates that the specified file is to be included 
in the link procedure as a library. The library file 
specification must be followed by the /LIBRARY 
switch. 

f ilenam6 . ext/EXECUTE 

indicates the name to be assigned to a save image 
file. The save image file specification must be 
followed by the /EXECUTE switch. If this field is 
not included, BATCH generates a temporary save image 
file (see Section 12.2.5), runs it, and then deletes 
the temporary file. 

The following $MACRO command assembles a program named PROGO.MAC and 
creates a temporary object file and a temporary listing file. 

* H R C R / LIST <■' B J E C T P R Q 9 . M ft C 



$MESSAGE 



12.4.17 $MESSAGE Command 

The $MESSAGE command is used to issue a message to the operator at the 
console terminal. It provides a means for the job to communicate with 
the operator. The $MESSAGE command has the form: 

$MESSAGE {/switch} message {Icomments} 

where : 
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/switch indicates the switches that can be appended to the 
$MESSAGE command. These switches are: 

/WAIT indicates that the job is to pause until 
the operator types a carriage return to 
continue or enters commands to the BATCH 
handler followed by a carriage return 
(see Section 12.7.3). 

/NOWAIT do not pause for operator response. 

message is a string of characters that must fit on one 
console line. The message is printed on the console. 

For example, if the following message is included in the input stream: 

*MESSfiGE,'UfiIT MOUNT SCRATCH TAPE ON MT@ 
The message: 

MOUNT SCRATCH TAPE ON MT0 

appears on the console terminal and a bell sounds. The operator 
mounts the tape and types carriage return to allow further processing 
of the job. (See Section 12.7.3 for operator interaction with BATCH.) 



$MOUNT 



12.4.18 $MOUNT Command 

The $MOUNT command assigns a logical device name and other 
characteristics to a physical device. When $MOUNT is encountered 
during the execution of a job, the entire $MOUNT command line is 
printed on the console terminal to notify the operator of the volume 
to be used. 

The $MOUNT command has the form: 

$MOUNT{/switch} dev:{/PHYSICAL}{/VID=x} {ldn: /LOGICAL} {Icomments} 

where: 

/switch indicates the switches that can be appended to the 
$MOUNT command. The switches are: 

/WAIT indicates that the job is to pause until 
the operator enters a response. If 
neither /WAIT nor /NOWAIT is specified, 
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/WAIT is assumed. BATCH rings a bell, 
prints a ?, and waits for a response. 
(The response can be input to the BATCH 
handler; see Section 12.7.3. 



/NOWAIT 



does not pause for operator response. 



dev 



/PHYSICAL 



/VID=x 
/VID="x" 



/WRITE 



/NOWRITE 



tells the operator to 
volume . 



WRITE-ENABLE the 



tells the operator to WRITE-PROTECT 
volume . 



the 



is required and specifies the physical device name 
and an optional unit number followed by a colon, 
e.g., DTI:. If dev is specified without a unit 
number, the operator can enter one in response to the 
? printed by the $MOUNT command. If the operator is 
to supply a unit number, do not use the /NOWAIT 
switch because it will assume unit 0. 

identifies the device specification as a physical 
unit specification. If neither /PHYSICAL nor 
/LOGICAL is specified, /PHYSICAL is assumed. 

provides volume identification. The volume identifi- 
cation is the name physically attached to the volume. 
It is included to help the operator locate the 
volume. This switch may appear only on the physical 
device file specification. If x contains spaces, it 



ldn: /LOGICAL 

is required to identify the logical device name, if 
any, to be assigned to the device. The logical 
device name specification must be followed by the 
/LOGICAL switch. 

The following are examples of the $MOUNT command: 

*M0UNTYWflI7/WR I TE DT : /V I D= BATCH 2 : /LOG I CflL 

This command instructs the operator to select a DECtape unit and mount 
DECtape volume BAT01 on that unit, WRITE-ENABLED. It informs the 
operator by printing: 



* MOUNT, •■' MAT 

?1 



'WRITE DT:/VID=BflT0i 



'LOG I CflL 



The operator selects a unit, mounts DECtape volume BAT01, 

WRITE-ENABLED, and responds to the ? by typing the unit number (e.g., 

1} followed by a carriage return. BATCH assigns logical device name 2 
to the physical device (e.g., DTI:) and proceeds. 

If no unit number response is necessary, e.g., 

*M0(JNTYWfl I 7YWR I TE DTI : £ : /LOG I CflL 



the operator responds with a carriage 
DECtape and WRITE-ENABLING the device. 



return after mounting the 
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12.4.19 $PRINT Command 

The $PRINT command is used to print the contents of the specified 
files on the listing device (LST:). This command has the form: 

$PRINT {/switch} dev : filnam. ext {/INPUT }{ ,dev : filnam2 .ext , . . . ,dev:- 
filnamn.ext} {Icomments} 

where : 

/switch indicates the switches that can be appended to the 
$PRINT command. The switches are: 

/DELETE indicates that input files are to be 
deleted after printing. 

/NODELETE indicates that input files are not to be 
deleted after printing. 

dev: is the device containing the files to be printed; if 
dev: is not specified, DK: is assumed. 

f ilnaml.ext- 

filnamn.ext indicate names of the files to be printed. wild 
cards can be used for the file name or extension. 

/INPUT indicates that the file is an input file; /INPUT is 
assumed if it is not entered. 

The following command prints a listing of files with extension .MAC 
that are stored on default device DK:. 

SPRINT *. MAC 

The following example creates listing files for the programs A and B, 
prints the listing files, and then deletes them. 

*MflCR0 A. MRC A/LIST 
SMRCRO B. MAC EVLI5T 
SPRINT/DELETE ft. LST, B. LST 
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12.4.20 $RT11 Command 

The $RT11 command allows the BATCH job to communicate directly with 
the RT-11 system. This command puts BATCH in RT-11 mode, i.e., until 
a line beginning with $ is encountered, all data images are 
interpreted as commands to the RT-11 monitor, RT-11 system programs, 
or to the BATCH run-time system. The $RTll command has the form: 

$RT11 {'comments} 

See Section 12.5 for a complete description of the RT-11 mode. 




12.4.21 $RUN Command 

The $RUN command requests execution of a program for which a save 
image file (.SAV) was previously created. It can also be used to run 
RT-11 system programs. 

The $RUN command has the form: 

$RUN dev: f ilnam.ext { Icomments} 

where filnam.ext is the name of the program (system or user) to be 
executed. If no extension is specified, .SAV is assumed. 

For example, the user can run PIP to print a directory listing. 

4RUN PIP 
*DflTfl 
LP:=DK:/L 
*E0D 
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12.4.22 $SEQUENCE Command 

The $SEQUENCE command is an optional command. If used, it must 
immediately precede a $JOB command. The $SEQUENCE command assigns a 
job an arbitrary identification number. The last three characters of 
a sequence number are assigned by BATCH as the first three characters 
of a temporary listing or object file (see Section 12.2.5). If a 
sequence number is less than three characters long, it is padded with 
zuoes on the left. 

The form of this command is: 

$SEQUENCE id {'comments} 

where id is an unsigned decimal number indicating the identification 
number of a job. 

The following are examples of the $SEQUENCE command: 

^SEQUENCE 3 ! SEQUENCE NUMBER IS 903 
*J0B 

^SEQUENCE 190 ! SEQUENCE NUMBER IS 139 
*J0B 



12.4.23 Example BATCH Stream 

The following example BATCH stream creates a MACRO program, assembles 
and links that program, and runs the save image file. It then deletes 
the object, save image, and source files created and prints a 
directory of DK: showing the files created by the BATCH stream. 

*JGB 

^MESSAGE THIS IS ft N EXAMPLE BATCH STREAM 

^MESSAGE NOW CREATE ft MACRO PROGRAM 

*CREATE/LIST EXAMPL. MAC 

. TITLE EXAMPL FOR BATCH 

. MCALL . REGDEF,. . V2. . , . PRINT, . EXIT 

. REGDEF 

. . V2. . 
START: . PRINT ttMESSAG 

. EXIT 
MESSAGE: . ASCI2 /EXAMPLE MACRO PROGRAM FOR BATCH/ 

. END START 
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*EOD 

*MACRO EXAMPL EXRMPL/OBJECT EXAMPL/LIST ! ASSEMBLE 

SLINK EXflMPL EXRMPL/EXECUTE !AND LINK 

SPRINT/DELETE EXflMPL. LST 

♦MESSAGE RUN THE MACRO PROGRAM 

♦ RUN EXflMPL !RND EXECUTE 

♦DELETE EXflMPL. OBJ+EXRMPL. SRV+EXAMPL. MAC 

♦MESSAGE PRINT R DIRECTORV 

♦DIRECTORV DK.EXAMPL. * 

♦MESSAGE END OF THE EXAMPLE BATCH STREAM 

♦ EQJ 

To run this batch stream, the user types the following at the console. 
Messages are printed by BATCH. 

. LORD BR, LP 
. ASSIGN LP : LOG 
. ASSIGN LP:LST 
. R BATCH 
+EXAMPL 

THIS IS AN EXAMPLE BATCH STREAM 

NOW CREATE A MACRO PROGRAM 

RUN THE MACRO PROGRAM 

PRINT A DIRECTORV 

END OF THE EXAMPLE BATCH STREAM 

END BATCH 

The above example BATCH stream produces the following log file on the 
line printer. 

5J0B 

MESSAGE THIS IS AN EXAMPLE HATCH STREAM 

1WESSAGE NCN CREATE A MACRO PROGRAM 

^CREATE/LIST EXANPL.NAC 

.TITLE EXAMPL FOR BATCH 

, "CALL .PEGDEF, .. V2. ,,, PRINT, .EXIT 

,REGDt.F 

,.V?.. 
START; .PRIMT **ES8AG 

.EXIT 
MESSAGE! .ASCIZ /EXAMPLE MACRO PROGRAM FOR BATCH/ 

.END START 

SEOD 

SMACRO EXAmpl EXAMPL/OBJECT EX A«Pl/UST I ASSEMBLE 

•ERRORS DETECTED! 
FREE CORE: 14 76*1, HBBQS 

* 

SLINK F.XAMPL FXAMPL/EXFCUTE ! AMD LINK 

SRRIMT/OELFTE FXA"Pi..LST 

SmESSaSE RUN THE MACRO PROGRAM 

*»UN ExiMPL. * A ?J i.) EXECUTE 
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EXAMPLE MACRO PROGRAM FOR 5ATCH 

SDELETE EXAMPL.OBJtfcXAMPL.SAVtEXAMpL.NAC 

SMESSAGE PRINT A DIRECTORY 

SDIRECTORY OKjEXAMPL.* 

q-MAY-75 
EXAMPt_.BAT 2 2B-APK-75 
EXAMPL.CTL 3 9-HAY-75 
2 FILES, 5 BLOCKS 
1436 FREE BLOCKS 

SMESSAGE END OF THE EXAMPLE BATCH STREAM 

SEOJ 

12.5 RT-11 MODE 

RT-11 mode provides the capability to enter commands to the RT-11 
monitor or to system programs and to create BATCH programs. RT-11 
mode may be entered with either the $JOB/RTll command or the $RTll 
command. If entered with the $JOB/RTll command, RTll mode remains in 
effect until the next $JOB command is encountered in the BATCH stream. 
If entered with the $RT11 command, RT-11 mode is in effect until a $ 
is encountered in the first position of the command line. 

The characters ., $, *, and tab or space appearing in the first 
position of a line (or card column 1) are interpreted as control 
characters and indicate the following: 

command to the RT-11 monitor, e.g., 

. R PIP 

* data line; any line not intended to go to the RT-11 

monitor or to the BATCH run-time handler, e.g., a 
command to the RT-11 PIP program: 

*FILE1. Dfl'IYD 

NOTE 

The * is not passed as data to the program. 
Comment lines (i) cannot appear on data lines 
as they would be considered as data. 

$ BATCH command. Causes exit from RT-11 mode if RT-11 

mode was entered with the $RTll command. For 
example: 

.?RT:i:t lEK'ffc.R RT-l.'i. f'iOL'E 

. R PIP 

H-DT!?:F3Lf::i. OfiT.-'D 

SDIKFCTORV DIG: ILEfiVE FOT-rii MODE" 

space/tab separator to indicate line directed to BATCH run-time 
handler. This separator is indicated by a -^ in the 
following descriptions. 
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12.5.1 Running RT-11 System Programs 

The most common use of RT-11 mode is to send commands to the RT-11 
monitor and to system programs. For example, the following commands 
can be inserted in the BATCH stream to run PIP and save backup copies 
of files on DECtape. 

*RT11 

. R PIP 

*DT1 :*. * = *. FORVX 

The user must anticipate and include in the BATCH input stream 
responses that are required by the called program, e.g., the Y. 
response to PIP's ARE YOU SURE? query. 

BATCH standard commands cannot be mixed with RT-11 mode data lines 
(i.e., lines beginning with an asterisk). For example, the proper way 
to do a $MOUNT within a sequence of RT-11 mode data commands is: 

*J0B/RTli 
. R MACRO 
* ft 1 = fl 1 

AMOUNT DT0:/PHVSICftL 
. R MACRO 
*31=DT :B1 
*B2=D7:B2 



12.5.2 Creating RT-11 Mode BATCH Programs 

RT-11 mode may be used by advanced system programmers to create BATCH 
programs. These BATCH programs consist of standard RT-11 mode 
commands (monitor commands, data lines for input to system programs, 
etc.) plus special RT-11 mode commands. These special commands are 
interpreted by the BATCH run-time handler to allow dynamic 
calculations and conditional execution of the RT-11 mode standard 
commands. The following facilities allow the user to create BATCH 
programs and to dynamically control the execution of these programs at 
run-time . 



to a constant or character (LET 



A. Labels 

B. Variable modification 

1) equating a variable 
statement) 

2) incrementing the value of a variable by 1 

3) reading a value into a variable 

4) conditional transfers on comparison of variable values 
with numeric or character values (IF and GOTO statements) 

C. Commands to control terminal I/O 

D. Other Control Characters 

E. Comments 



12.5.2.1 Labels — Labels in RT-11 mode are user-defined symbols that 
provide a symbolic means of referring to a specific location within a 
BATCH program. If present, a label must begin in the first character 
position, must be unique within the first six characters, and must 
terminate with a colon (:) and a carriage return/line feed 
combination. 
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12.5.2.2 Variables — A variable in RT-11 mode is a symbol 
representing a value that can change during program execution. The 26 
variables permitted in a BATCH program have the names A-Z; each 
variable requires one byte of physical storage. The user may assign 
values to variables in a LET statement. These values may then be 
tested by an IP statement to control the direction of program 
execution. 

Variables may be assigned values with a LET statement of the following 
form: 

Hlet x="c 

where x is a variable name A-Z and "c indicates the ASCII value of a 
character. For example: 

-»|LET A="0 

indicates that the value of variable A is equal to the 7-bit ASCII 
value of the character (60) . 

The LET statement can also specify an octal value in the form: 

Hlet A=n 

where n is an 8-bit signed octal value in the range to 377; 
positive numbers range from to 177 and negative numbers from 200 to 
377 (-200 to -1) . 

Variables may be used to introduce control characters, such as 
ALTMODE, into a BATCH stream. For example, wherever 'A' appears in 
the following BATCH stream, BATCH substitutes the contents of variable 
A (the code for an ALTMODE) : 

SJ0B/RT11 

LET fl=33 

!fl IS AN ALTMODE 
. R EDIT 
+ EBFILE. MAC A" A' 

!EDIT FILE TO CHANGE THE VERSION NUMBER TO 2 
*GVERSIuN = 'fl'DI2' A"' fl' 
*EX'R"R' 
*E0J 

The value of a variable can be incremented by 1 by placing a percent 
sign (%) before the variable. For example: 

H%A 

indicates that the unsigned contents of variable A are to be increased 
by 1. 

Conditional transfers of control according to the value of a variable 
are indicated with an IF statement. The IF statement has the form: 

-HlF(x-"c) labell, label2, label3 

or 

HlF(x-n) labell, label2, label3 

where x is the variable to be tested, "c is the ASCII value to be 
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compared with the contents of the variable, or n is an octal value in 
the range to 377, and labell, label2, and label3 are the names of 
labels included in the BATCH stream. 

When BATCH evaluates the expression (x-"c) or (x-n) , the BATCH 
run-time handler transfers control to: 

• labell if the value of the expression is less than zero. 

• label2 if the value of the expression is equal to zero. 

• label3 if the value of the expression is greater than zero. 

If one of the labels is omitted, and the condition is met for the 
omitted label, control transfers to the line following the IF 
statement. 



NOTE 

Since this comparison is a signed byte 
comparison, 377 is considered to be -1. 



The characters + and - allow the user to control where BATCH begins 
searching for labell, label2, and label3. If the label is preceded by 
a minus sign (-) , the label search starts just after the $JOB command. 
If a plus sign (+) or no sign precedes the label, the label search 
starts after the IF statement. For example, the following statement: 

-|lF(B-"9) -LOOP, LOOP1, 

transfers program control to the label LOOP following the $JOB command 
if the contents of variable B are less than the ASCII value of 9 or to 
the label LOOP1 following the IF statement if B is equal to ASCII 9. 
If the contents of variable B are greater than the ASCII value of 9, 
program control goes to the next BATCH statement in sequence. 

The GOTO statement unconditionally transfers program control to a 
label specified as the argument of the statement. This statement may 
be one of the following three forms: 



-\ GOTO label 



-»| GOTO +label 
-J GOTO -label 



transfers control to the first occurrence of label 

that appears after this GOTO statement in the 

BATCH stream. 

same as GOTO label. 

transfers control to the first occurrence of label 

that appears after the $JOB command. 



If the label is not found, transfer goes to $EOJ. 

The following GOTO statement transfers control unconditionally to the 
next label LOOP if such a label appears in the BATCH stream following 
the GOTO statement. 

-*|GOTO LOOP 
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NOTE 

If a label cannot be found, e.g., a 
minus sign was intended but omitted, the 
BATCH handler searches until the end of 
the CTL file is reached and ends the 
job. 



12.5.2.3 Terminal I/O Control — Commands may be issued directly to 
the BATCH run-time handler to control console terminal input/output to 
the log file. If none of the following commands is entered, TTYOUT is 
assumed. 

-*|NOTTY do not write terminal input/output to the log file. 
Comments to the log will still be logged. 

-»|TTYIN write only terminal input to the log file. 

-»|TTYIO write terminal input and output to the log file. 

HTTYOUT write only terminal output to the log file (default). 



12.5.2.4 Other Control Characters — Other control characters allowed 
in an RT-11 mode command that begins with a period {.) or an asterisk 
(*) indicate the following: 

'text' command to BATCH run-time handler, where text can be 
one of the following: 

CTY accept input from the console terminal? 

notify the operator that action is 
required by ringing a bell and printing 
a ?. 

FF output current log buffer. 

NL insert a new line (line feed) in the 

BATCH stream. 

x insert contents of variable where x is 

an alphanumeric variable A-Z, indicates 
that the contents of the variable are to 
be inserted as an ASCII character at 
this place in the command string. 

"message" direct the message to the console 
terminal . 

Example 1: 

The following commands allow the operator to enter the name of a MACRO 
program to be assembled. The BATCH stream contains: 

*J0B/RT11 

. R MfiCRO 

*' "ENTER MfiCRO COMMAND STRING"" CTV 

*E0J 

The operator receives the following message at the terminal; he types 
a response, followed by carriage return, and BATCH processing 
continues. 
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ENTER MACRO COMMAND STRI NG?FI LE, FI LE=FILE 

Example 2: 

The user may want to run the same BATCH file on several systems with 
different configurations and would want to assign a device 
dynamically. The following RT-11 mode command allows the user to 
request that the listing device name be entered by the operator. 

.ASSIGN ''"PLEASE TVPE LST DEVICE NAME '"' ' CTV LST 

The operator receives the message and responds with the device to be 
used as the listing device (DT2:). 

PLEASE TVPE LST DEVICE NAME?DT2: 



12.5.2.5 Comments — Comments can be included in RT-11 mode as 
separate comment statements. This is accomplished by typing a 
separator followed by a ! and the comment, e.g., 

— | 'OPERATOR ACTION IS REQUESTED IN THIS JOB. BE PREPARED. 



12.5.3 RT-11 Mode Examples 

The following are examples of BATCH programs using the RT-11 mode. 

Example 1: 

This BATCH program assembles, lists, and maps 10 programs with only 12 
BATCH commands. 

.MOG/RTli ! ASSEMBLE, LIST, MRP PROG© TO PROGS" 

T T V I 

IWRITE TERMINAL I/O TO THE LOG FILE 

LET N="@ 

! START AT PROG0 
LOOP : 
. R MACRO 

■•+PR0G' N'- , LOG : ,'C = PR0G' N' /H; TTM 
. R LINK 
*, L0G:=PRQG'N' 

y.n 

1 INCREMENT VARIABLE N 

IF<N-"9>-L00P, -LOOP, END 

1TEST FOR END 
END: 
SEOJ 

Example 2: 

The following program allows the user to set up a master control 
stream to run several BATCH jobs with one call to BATCH. First the 
user sets up a BATCH job (INIT.BAT) that will $CHAIN to the master 
control stream: 
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SJ0B/RT11 

LET I="0 

1 IN I T I RL IZE INDEX 
SCHAIN MASTER ! GO TO MASTER 
*EOJ 

The following is the master control stream (MASTER.BAT) to which INIT 
chains. 

3J0B/RT11 ! MASTER CONTROL STREAM 

;-;i 

!BUMP INDEX BV 1 

IF <.!-"?■>, > END 
. R BATCH 

'THIS IS fl *CHflIN 
*JOB' I' 

'RUNS J0B1-J0B7 
END: 

^MESSAGE END OF BATCH RUN 
*EQJ 

Each job to be run by MASTER.BAT must contain the following: 

$JOB 

! BATCH COMMANDS 
$CHAIN MASTER 
$EOJ 

The master control stream is activated by calling BATCH as follows: 

. R BATCH 
* I N I T 



12.6 CREATING BATCH PROGRAMS ON PUNCHED CARDS 

To create a BATCH program on punched cards, the user punches into the 
cards the commands as described in Section 12.4. Each command line 
occupies a single punched card. Only one card, the EOF card, is 
different from the standard BATCH commands. The EOF (end-of-f ile) 
card terminates the list of jobs from the card reader. 

To create the EOF card, hold the MULT PCH key on the keypunch keyboard 
while typing the following characters (DEC029 codes, see Appendix H 
for DEC026 codes) : . 

-&016789 

This procedure produces an EOF card with holes punched in the first 
column (see Figure 12-1) . 
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10 000000000 0000 000000 000000 0000000 000000 000000 0030000000000000000 00 0000 000 

I Z 3 < S 6 2 8 9 10 11 12 13 MIS If 1718 19 21 21 22 23 !1 IS 2S 27 28 29 30 ]l 32 33 3< 35 36 II 33 13 ill] 12 13 H« 38 (1 (0«9 SO 51 S2 S3 5! 5S 56 57 5B SS 8061 62 63 S< 55 66 6 J 68 69 18 71 11 13 H IS li II 78 lift 

H n in n n i ii ii ii i ii n 1 1 1 m 1 1 1 1 1 1 1 1 1 1 1 1 ii ii 1 1 1 1 n 1 1 1 1 11 1 1 1 n i u I n 11 1 1 1 1 1 1 ii 1 1 

222222222??22Z22222222222222222222222222222222222222Z222222222222222222222222222 

33333 333333333333333333333333333333333333333333333333 333333333333333333333333 333 

4 4 4 4 4 4 4 4 4 4 4 4 4 4 44 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 « 4 4 4 4 4 4 4 4 4 4 1 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 

5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 S 5 5 5 5 5 5 5 5 5 5 5 5 5 5 S 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 S 

1 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 G 6 « G 6 6 6 6 6 6 G G 6 6 G 6 6 6 6 6 6 6 G 6 6 6 G 6 6 6 6 6 6 6 6 6 6 6 6 6 G 6 6 6 6 6 G G 6 6 G G 6 6 G 6 G 6 6 G G 6 5 6 

tiiiiniiiiiinnmnniinmiiminnnnniniimnmimmmmnmn 

1 8 8 6 8 8 8 8 8 8 8 3 8 8 8 8 8 8 B 8 8 8 8 8 6 8 8 8 8 8 8 8 8 8 8 8 8 8 6 8 8 8 8 B 8 8 8 8 8 8 8 8 8 8 8 6 8 8 8 8 3 6 8 3 8 a 6 8 8 8 8 6 

1 9 S 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 S 9 9 9 8 9 9 9 9 3 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 3 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 !) 9 9 9 9 

' 2 3 < S 6 : 9 111! 12 13 H 15 IS II 16 19 20 21 11 VV Z5 it V ;i 23 30 31 1» 3] i' 35 V, 31 j3 is H iH2.ll '"5 1! « tii M ii 52 ii i< Si S5 17 SI S3 60 61 62 63 61 65 66CT 11 69 70 II inill'iil'lliil 

ibm rsogp _ 

Figure 12-1 EOF Card 



12.6.1 Terminating BATCH Jobs on Cards 

To terminate BATCH, type \F, followed by a carriage return, put two 
EOF cards and a blank card in the reader, and ensure that the card 
reader is ready. Note that a small card deck (less than 512 
characters) may require more than two EOF cards to terminate the deck. 



12.7 OPERATING PROCEDURES 



12.7.1 Loading BATCH 

After the RT-11 system has been bootstrapped and the date and time 
entered, the BATCH run-time handler must be made resident by typing 
the RT-11 LOAD command as follows: 

. LORD Bfi 

The BATCH run-time handler must be detached with the /U switch to the 
BATCH compiler command line (see Section 12.7.2) before it is removed 
with the RT-11 command UNLOAD. 

Unless the log device is SY: or any device for which the handler is 
already resident, the BATCH log device must be made resident. The log 
device is loaded by typing: 

.LOAD log 
where log is the device to which the BATCH log is to be written, e.g., 
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. LORD LP 

The loading of device handlers can, of course, be done with a single 
LOAD command, e.g., 

. LOAD BA, LP 

The log device must then be assigned the logical device name LOG. 
This is accomplished with the RT-11 monitor command ASSIGN in the 
form: 

.ASSIGN log:LOG 

For example, if LP: is the log device, type: 

. ASSIGN LP: LOG 

The device to be used for listing files must be made resident with the 
LOAD command and then assigned the logical device name LST: . This is 
accomplished with the RT-11 ASSIGN command in the form: 

.ASSIGN lisdev:LST 

where lisdev is the physical device to be used for listings. If, for 
example, listings are to be produced on the line printer, type: 

. ASSIGN LP: LST 

NOTE 

The ASSIGN command with no arguments 
should not be used in a BATCH program 
since it would then deassign the log 
and list devices, possibly causing the 
BATCH job to terminate. 

The BATCH Run-Time Handler input device (Compiler output device) must 
also be made resident. If this device is already resident or is SY: , 
it need not be loaded. For example, to load the DECtape handler as 
the input device, type: 

. LORD DT 

If the input file to the BATCH Compiler is on cards, the card reader 
handler must be loaded by typing: 

. LOAD CR 

NOTE 

If input is on cards, the RT-11 monitor 
command SET must be used (before the 
handler is loaded) to specify CRLF and 
NOIMAGE modes, i.e., 

. SET CR CRLF 

to append a carriage return/line feed 
combination to each card image, and 

. SET CR NO IMAGE 

to translate the card by packing card 
code into ASCII data, one column per 
byte . 
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12.7.2 Running BATCH 

When all necessary handlers have been loaded, the BATCH Compiler is 
run as follows: 

. R BATCH 

BATCH responds by printing an asterisk (*) to indicate readiness to 
accept command string input. In response to the *, type the output 
file specifications for the control file followed by an equal sign or 
left angle bracket, followed by the input file specifications for the 
BATCH file as follows: 

{{spc0}{,spcl}{/switch}=}spc3{,. . . }{ ,spc8/switch } 

where: 

spcO is the BATCH compiler output device and file to be 
used by the BATCH run-time handler. The device 
specified must be random-access. This file should 
not be deleted or moved by the job that is within 
it; nor should the system ever be compressed from 
within a batch job. If spcO is omitted, a file is 
generated on the default device (DK:) with the same 
name as the first input file but with a .CTL ex- 
tension. If no extension is specified, .CTL is 
assumed. 

spcl is the log file created by the BATCH run-time 
handler. If no log device is specified, LOG: is 
assumed. The device name specified for spcl must be 
that assigned to LOG:. 

The size of a log file on a file-structured device 
may be changed from the default size of 64 (decimal) 
by enclosing the requested size in square brackets. 
For example: 

*,FILE.LOG[10]=FILE 

The default extension for spcl is .LOG. 

spc3-spc8 are input file specifications. If no input 
extensions are specified, the default extension is 
.BAT. If a .CTL file is specified, a precompiled 
file is assumed and it must be the only file in the 
input list. 

/switch is one or more of the following: 

/N compiles but does not execute; creates 

BATCH control file (.CTL), generates an 
ABORT JOB message at the beginning of 
the log file, and returns to RT-11 
monitor . 

/T:n if n=0, sets the /NOTIME switch as 
default on the $JOB command; if n=l, 
the default switch on the $JOB command 
is /TIME. 
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/U indicates that BATCH compiler is to 

detach the BATCH run-time handler from 
the RT-11 monitor for subsequent 
removal. The prompting message ! UNLOAD 
BA! is printed. 



NOTE 

The RT-11 monitor command UNLOAD 
BA must be specified to actually 
remove the handler. The handler 
must be reloaded before BATCH is 
run again. 



/V prints version number of BATCH compiler 

/X indicates that input is a precompiled 

BATCH program (used when .CTL is not 
the extension or when the extension is 
omitted) . 



Example 1; 



In the following example, the user calls BATCH to compile and execute 
the three input files (PR0G1.BAT, PROG2.BAT, PROG3.BAT), to gen- 
erate on DK: the compiler output files and to generate on LOG: a log file. 



. ft BATCH 

*PR0G1. BAT, PROGS. BflT, PROGS:. BAT 



Example 2; 



The following commands compile and run SYBILD.BAT, printing the 
version number of BATCH. 

. R BATCH 
*SVBILD/V 
BATCH V01-82 

Example 3: 

The following commands compile PROTO.BAT to create PROTO.CTL but do 
not run the compiled program. 

. R BATCH 
*PR0T0/N 

Example 4: 

Type the following commands to unlink BA.SYS from the monitor and to 
unload it. 

. R BATCH 

'UNLOAD BA! 

. UNLOAD BA 
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Example 5: 

The following commands compile FILE. BAT from magtape to create 
FILE.CTL on DK1:, execute the compiled file, and create a log file 
named FILE. LOG of size 20 on LOG:. 

. R BATCH 

*DK1:FILE, FILEC 28 ]=MT : FILE 

Example 6: 

The following commands execute a precompiled job called FILE.TST. 

. R BATCH 
*FILE. TST/X 

Example 7: 

The following commands execute a precompiled job called FILE.CTL. 

. R BATCH 
*FILE/!< 

Example 8: 

The following commands accept input from the card reader to create on 
DK: a file called TEMP.CTL and execute that file. 

. R BATCH 
*CR: 

Example 9: 

The following commands accept input from the card reader to create on 
DK: a file called JOB.CTL and execute that file. 

. R BATCH 
*J0B=CR: 



12.7.3 Communicating with BATCH Jobs 

During the execution of a BATCH stream, the operator may be requested 
to supply action or provide information or to insert a command line 
into the BATCH stream. The operator can accomplish this by typing 
directives to the BATCH handler Via the console terminal. 

NOTE 

These directives are equivalent to the 
compiler output generated by BATCH in 
the .CTL file. The .CTL file is an 
ASCII file that can be listed using PIP. 



These directives have the form: 

\dir 
where dir is one of the directives listed in Table 12-6. 
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To use these directives, the operator must get control of the BATCH 
run-time handler by typing a carriage return on the console terminal. 
When BATCH executes a command, it notices the carriage return and 
prints a carriage return/line feed combination at the terminal. The 
directives in Table 12-6 may then be entered by the operator; those 
most useful to the operator are marked with an asterisk (*) . 

Table 12-6 
Operator Directives to BATCH Run-Time Handler 

Directive Explanation 

\@ Send the characters that follow to the console 

terminal . 

*\A Change the input source to be the console terminal. 

*\B Change the input source to be the BATCH stream. 

*\C Send the following characters to the log device. 

*\D Consider the following characters as user data. 

*\E Send the following characters to the RT-11 monitor. 

*\F Force the output of the current log block. If this 

directive is followed by any characters other than 
another BATCH backslash (\) directive, the BATCH job 
prints an error message and terminates; control 
returns to the RT-11 monitor. 

\G Get characters from the console terminal until a 

carriage return is encountered. 

\Hn Help function to change the logging mode where n 

specifies the following: 

Log only .TTYOUT and .PRINT. 

1 Log .TTYOUT, .PRINT, and .TTYIN 

2 Do not log .TTYOUT, .PRINT, and .TTYIN 

3 Log only .TTYIN 

\Ivxlabell?label2?label3? 

IF statement which causes conditional transfer, where v 
is a variable name in the range A-Z; x is a value for 
the signed 8-bit comparison (v-x) ; and labell, label2, 
label3 are 6-character labels to which control is 
transferred under certain conditions. (All labels must 
be six characters in length; if too short, pad with 
spaces.) If v-x is less than 0, control transfers to 
labell; if v-x is equal to 0, control goes to label2; 
if v-x is greater than 0, control goes to label3. The 
direction for the label search is indicated by ?; if ? 
is 0, the search begins at the beginning of this job; 
if ? is 1, the label search begins after the IF 
statement. 

(continued on next page) 
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Table 12-6 (cont.) 
Operator Directives to BATCH Run-Time Handler 



Directive Explanation 



\Jlabel? Jump, unconditional transfer; where label is a 
6-character label and ? is or 1. (All labels must 
be six characters in length; if too short, pad with 
spaces.) If ?=0, label is a backward reference; if 
?=1, label is a forward reference. 

\KvO Increment variable v where v is a variable name in the 

range A-Z. 

\Kvln Store the 8-bit number n in variable v. 

\Kv2 Take the value in variable v and return it to the 

program (via .TTYIN) . 

\Llabel Insert label as a 6-character alphanumeric string in 
the BATCH stream. (All labels must be six characters 
in length; if too short, pad with spaces.) Labels must 
not include backslash characters. Characters beyond 
six are ignored. 

Example 1: 

The operator may wish to interrupt the BATCH handler to enter 
information from the console as a result of a /WAIT or 'CTY' in the 
BATCH stream. For example, the following message appears at the 
terminal . 

*MESSfiGE/WfiIT WRITE NECESSARY FILES TO DISK 

To divert BATCH stream input from the current file to the console 
terminal, the operator types a \E and can then enter commands to the 
RT-11 monitor until he types a \B. Control then returns to the BATCH 
stream. For example, to respond to the preceding message, the 
operator types: 

WRITE NECESSARY 'FILES TO DISK 
?\fi\ER PIP changes input source to TT: 

PIP and calls the RT-11 monitor to 

\ER PIP run PIP 

writes FILE. MAC from DT2: to 
SDRK:*. *--:DT2:F-ILE. MPO,-'X RK : 

\E\F\B outputs log block and returns 

control to the BATCH stream 

Example 2: 

The following BATCH program allows the user to make frequent edits to 
a file and list only the edits. First the user creates a BATCH 
program which will assemble with a listing and link the file. This 
BATCH program, called COMPIL.BAT, contains: 

SJGEVRTil 

T T V I 

! WRITE TERMINAL I/O TO THE LOG FILE 
. R MACRO 



12-51 July 1975 



BATCH 



ICflLL THE MRCRO ASSEMBLER 
*FILE, FILE/C=FILE 

*MESSflGE/WHIT OK TO TVF'E EDIT COMMANDS 
. R LINK 

ICflLL THE RT-11 LINKER 
♦FILE, LOQ:=FILE 
$EOJ 

At run-time, the user can insert commands into the BATCH stream via 
the console terminal. These commands will search for the section of 
the listing file that has been edited and then list this section to 
the log. The command must be inserted after the R MACRO command but 
before the R LINK command. The operator types the following to use 
COM PI L„ BAT. 

. LOAD BH, Lf 
. flSSKiN LF'ILOG 
. R BATCH 
*C0MPIL 

OK TO TVF'E EDIT COMMANDS 
?\A\E 
\ER EDICT 

■+ERFILE, I..ST** find FILE.LST on system device 

•+EWF1LE. LST** 

■+PBEL.L : * = J*$ find BELL, move pointer back 

*/!_*$ * print contents of buffer to log and console 

*EX** print remainder of input file to log 

\E\C\B return to BATCH 

END BATCH 

12.7.4 Terminating BATCH 

When BATCH terminates normally, it prints: 

END BATCH 

and returns control to the RT-11 monitor. 

To abort BATCH while it is executing a BATCH stream, the best method 
is to interrupt the BATCH handler by typing a carriage return. When 
BATCH executes the next command after the carriage return was typed,, 
it prints a carriage return/line feed combination at the console 
terminal and the operator has control. The operator then types \F 
followed by a carriage return. The BATCH handler responds with the FE 
(forced exit) error message and writes the remainder of the log 
buffer. Control returns to the RT-11 monitor. 

CTRL C can be typed to terminate BATCH but is a more drastic method 
than that described above. CTRL C should be used when BATCH is in a 
loop or when a long assembly is running. 



12.8 DIFFERENCES BETWEEN RT-11 BATCH AND RSX-11D BATCH 

For those users who may wish to run their RT-11 BATCH programs under 
RSX-11D, or vice versa, Table 12-7 lists the differences between the 
two programs. A user who plans to run his BATCH programs under both 
systems should ensure that the programs are compatible with both RT-11 
and RSX-11D BATCH. 
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Table 12-7 
Differences Between RT-11 and RSX-llD BATCH 



Differing Aspects 


RT-11 


RSX-llD 


File descriptors 


dev: f ilnam.ext/sw 


SY: f ilnam.ext/sw 


Default listing extension 


.LST(or .LIS) 


.LIS 


Executable file extension 


.SAV 


.EXE 


Incompatible commands 


$BASIC 

$CALL 

$CHAIN 

$LIBRARY 

$RT11 

$SEQUENCE 


$MCR 


Incompatible switches 


$COPY/DELETE 

$CREATE/DOLLARS 

$CREATE/LIST 

$DATA/DOLLARS 

$DATA/LIST 






$DIR file/LIST 


$DIR file/DIRECTORY 




$DISMOUNT/WAIT 






$DISMOUNT lun:/LOGICAL 




$FORTRAN/DOLLARS 






$ FORTRAN/MAP 






$JOB/BANNER 


$JOB/NAME 




$JOB/LIST 


$JOB/LIMIT 




$J0B/RT11 


$JOB/MCR 




$JOB/TIME 






$JOB/UNIQUE 






$LINK/LIBRARY 


$LINK/MCR 




$LINK/OBJECT 






$MACRO/CREF 






$MACRO/DOLLARS 






$MACRO/LIBRARY 






$MACRO/MAP 






$MESSAGE/WAIT 






$MESSAGE/WRITE 






$PRINT/DELETE 




$DATA input 


appears as if from 


appears as if from 




input 


a file named 
FOR001.DAT 


Logical device names 


in $MOUNT and 


logical unit numbers 




$DISMOUNT 


only 


$RUN 


file name must be 


RSX11DBAT.EXE is 




specified 


default 



12.9 ERROR MESSAGES 

Two types of errors are reported by the BATCH system: user BATCH 
stream errors found by the compiler and noted in the BATCH log file, 
and system or operator errors noted at the console at run-time. Note 
that when BATCH is called from within a BATCH stream, both types of 
error messages are sent to the log. 
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The following messages detail errors found by the compiler and noted 
in the log file. An error is indicated by the printing of the 
erroneous line, an uparrow (or circumflex) under the error, and one of 
the following messages. 



Message 
ABORT JOB 



Meaning 

An error has occurred in compiling 
a BATCH program; the compiler 
forces the job to abort. All error 
messages are printed in the log 
file. 



BAD CONSTRUCTION 



BAD SEQUENCE ARGUMENT 



In RT-11 mode, an IF statement is 
not in the correct form or there 
was an illegal "text* directive. 

The identification number specified 
in a $SEQUENCE command is not 
numeric . 



BAD VARIABLE 



The variable specified is not one 
of the characters A-Z. 



BAD VI D 



BATCH HANDLER NOT RESIDENT 



BATCH STACK OVERFLOW 



The volume identification specified 
in a $MOUNT command is not in the 
correct form, e.g., the equal sign 
(=) or the text is missing. 

The BATCH run-time handler was not 
loaded with the RT-11 LOAD command 
(see Section 12,7,1). 

There are too many nested $CALL 
commands in the BATCH stream. 



CC 'MAND NOT UNIQUE 



DISMOUNT ERROR 



The spelling of a command is not 
unique (appears only when 
$JOB/UNIQUE was specified) . 

The logical device name specified 
does not exist. 



'$' MISSING 



A $ is not present in the first 
position of the command line (or 
card column 1) . 



ILLEGAL '+' 



The + construction was used when 
not allowed (e.g., in a $RUN or 
$BASIC input file descriptor) , 
there is a + in an output file 
descriptor, or a + terminates a 
control statement. 



ILLEGAL CHARACTER 



The character specified is not used 
in proper context. 



(continued on next page) 
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M essage 
ILLEGAL SWITCH 

ILLEGAL SWITCH COMBINATION 

LINE TOO LONG 
MULTIPLE SWITCH 



NO $EOJ 



NO FILE 



NO FILE NAME BEFORE 



NO LOGICAL DEVICE 



NO PHYSICAL DEVICE 



PLEASE ASSIGN LOG,LST 



PLEASE LOAD LOG HANDLER 



SEPARATOR MISSING 



SWITCH NOT UNIQUE 



TOO MANY FILE DESCRIPTORS 



UNKNOWN COMMAND 



Meaning 

The switch name specified is not a 
legal RT-11 BATCH switch or is not 
legal for this field. 

More than one switch of the same 
type, e.g., /INPUT and /SOURCE 
exists on same command line. 

The input line entered is greater 
than 80 characters. 

The same switch is specified more 
than once in a single command line. 

A $JOB or $SEQUENCE command appears 
without a preceding $EOJ to end the 
previous job. 

No file descriptor was found in the 
BATCH stream where one was 
expected, or no file name was 
entered in the $CREATE command. 

An extension was specified but no 
file name preceded it. 

No logical device is specified in a 
$MOUNT command. 

No physical device is specified in 
a $MOUNT command. 

The log device (LOG:) and/or the 
listing device (LST:) were not 
assigned (see Section 12.7.1). 

The log device handler is not 
resident (see Section 12.7.1). 

A file descriptor was not 
terminated by a space, a +, a , or 
a carriage return. 

The spelling of a switch is not 
unique (appears only when 
$JOB/UNIQUE is specified). 

More than six file descriptors are 
specified in a $command line. 

The command specified with a $ in 
character position 1 is not a legal 
BATCH command. 
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The following messages, generated by system or operator errors, are 
noted on the console at run-time. 



Message 

BAD COPY OF HANDLER 



BAD SWITCH 



BATCH FATAL ERROR 



BATCH STACK OVERFLOW 



BC 



END BATCH 

EOF WITH NO EOJ 

FE 



ILLEGAL COMMAND LINE 



ILLEGAL DEVICE 



ILLEGAL LOG DEVICE 



INPUT ERROR 



Meaning 

The copy of BA.SYS in memory is 
bad. BATCH cannot be run until 
BA.SYS is unloaded and reloaded 
(see Section 12.7.1). 

The command line to the BATCH 
Compiler contains an illegal 
switch. 

A nonrecoverable error has occurred 
(e.g., the system device is 
WRITE-LOCKed) ; BATCH must be 
rerun. The system may have to be 
rebootstrapped . 

There are too many nested $CALL 
commands in the BATCH stream. 

Fatal error. A Bad Code was found 
in the control file by the BATCH 
handler. This can happen when a 
.CTL file has been garbled or if an 
editing mistake was made by the 
programmer when altering or 
creating the file with EDIT. 

A BATCH job has been terminated. 

A file was not terminated with a 
$EOJ command . 

Fatal error. A Forced End occurred 
due to the appearance in the .CTL 
file of an illegal \F followed by a 
carriage return or BATCH was 
terminated from the console with a 
\F followed by a carriage return. 
The \F must be followed by another 
BATCH control directive. 

Command line to the BATCH compiler 
is incorrect. 

A $DISMOUNT command was attempted 
on device that was not assigned. 

Magtape, cassette, or a read-only 
device (e.g., PTR:) was specified 
as the log device. 

An error occurred while BATCH was 
attempting to read the compiler 
input file (.BAT) . 



(continued on next page) 
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M eaning 
INPUT FILE? 

10 



Message 



LOG DEVICE ERROR 



LU 



NO CONTROL FILE 



OUTPUT DEVICE FULL 



OUTPUT ERROR 



OUTPUT FILE NOT OPEN 



RETURN FROM CALL ERROR 



TOO MANY OUTPUT FILES 



! UNLOAD BA! 



An input file 
specified to 
command line. 



descriptor 
the BATCH 



was not 
compiler 



Fatal error. An Input or Output 
error occurred when the BATCH 
handler was attempting to read the 
•CTL file or write to the log file. 
The probable cause of this error is 
a log file overflow. 



An error 
device . 



occurred on 



the 



log 



Fatal error. A Lock Up occurred in 
the BATCH handler because it could 
not find a free channel or a 
channel it could use. This can 
happen if all channels are opened 
for magtape or cassette operations 
within the BATCH stream. 

The .CTL file was probably sent to 
a nonf ile-structured device (e.g., 
LP:) without using the /N switch to 
inhibit execution. 

The temporary file (.CTL) created 
by BATCH is too large for the 
specified device. Try compressing 
the device with PIP, or use another 
device. 

An error occurred while BATCH was 
attempting to write the compiler 
output file (.CTL) or magtape or 
cassette was specified as the .CTL 
output device. 



Fatal error, 
write on 
opening it. 



BATCH 
a .CTL 



attempted to 
file without 



Fatal error. BATCH cannot read 
control file which called a 
subprogram. BATCH cannot resume 
execution on return from call. 

A third output file was specified 
to the BATCH compiler; only two 
output files may be specified. 

Prompting message printed when /U 
switch is given to the compiler. 
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APPENDIX A 
ASSEMBLY, LINK, AND BUILD INSTRUCTIONS 

The information that formerly appeared in this appendix has now been 
incorporated into the RT-11 System Gen e ration Manual , DEC-11-0RGMA-A-D. 
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APPENDIX B 
COMMAND AND SWITCH SUMMARIES 



Command and switch summaries of the various RT-11 system 
programs are grouped here for the user's convenience, 
appropriate chapter for details. 



and utility 
Refer to the 



B.l KEYBOARD MONITOR (Chapter 2) 



B . 1 . 1 Command Summary 

Only those command characters underlined need be entered; 
lines are terminated by typing a carriage return. 



all command 



Command Format 



ASSIGN dev:udev 



B location 



CLOSE 



DATE dd-mmm-yy 



Used Under 



F/B,S/J 



F/B,S/J 



F/B,S/J 
(B only) 

F/B,S/J 



D location 



value 1 , value 2 , . 
F/B,S/J 



Explanation 

Assigns a user-defined name (udev) as an 
alternate name for a device (dev) . 
Deassigns synonyms when used without any 
arguments . 

Sets a relocation base (location) , which 
is an octal address to be used as a base 
address for subsequent Examine and 
Deposit commands. 

Causes all currently open files to be- 
come permanent. 

Enters the indicated day-month-year 
(dd-mmm-yy) ; this date is then assigned 
to newly created files, new device 
directory entries, and listing output. 
When used without an argument, the 
current date (as entered) is printed. 



. ,valuen 

Deposits the specified values starting 

at the given location (location 

represents an octal address which is 
added to the base address to obtain the 

actual address at which values will be 
deposited) . 
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Command Format 



Used Under 



E location m-location n 

F/B,S/J 



Explanation 

Prints the contents of the specified 
locations in octal on the console 
terminal (location represents an octal 
address which is added to the base 
address to obtain the actual address 
examined) . 

FRUN dev:filnam.ext/Nin/S:n/P Initiates a foreground job which exists: 

F/B on the device indicated (dev) under the 
(F only) specified filename and extension. /N:n 
is optionally used to allocate n 
(decimal) words over and above actual 
program size; /S:n is optionally used 
to allocate n words for stack space; /F 
is used for debugging purposes (the load 
address is printed but the program must 
be started using RSUME) . 

Loads the specified memory image file 
(filnam.ext) into memory from the 
indicated device (dev:) . 

F/B,S/J Used (after GT ON) to clear the display 
processor and resume printout on the 
console terminal. 

F/B,S/J Enables the display processor so that 
the display screen replaces the console 
as the terminal output device. /L:n may 
be optionally used to designate the 
number of lines to display (12" screen - 
K»n<»37 octal; 17" screen - 10n<-50 
octal) . /T:n may be optionally used to 
indicate the top position of the scroll 
display (12" screen - K=»n<-1350 octal; 
17" screen - K=n<=1750 octal) . 

F/B,S/J Resets background system tables; makes 
(B only) nonresident all handlers not loaded and 
purges background's I/O channels. 



GET dev: filnam.ext F/B f S/J 



GT OFF 



GT ON/L:n/T:n 



INITIALIZE 

LOAD dev,. .. 

LOA D dev-B,dev-F,, 

_R_ filnam.ext 

REENTER 
RSUME 



F/B f S/J Makes a device handler resident for use. 



F/B 

F/B,S/J 
(B only) 



F/B,S/J 



F/B 

(F only) 



Makes a device handler resident for use 
with background and foreground jobs. 

Loads the specific memory image file 
(filnam.ext) into memory from the system 
device and starts execution. 



Starts a program at its reentry 
(i.e., its start address -2). 



address 



RUN dev: filnam.ext F/B,S/J 

(B only) 



Resumes execution of a foreground 
program where it was suspended. 

Loads the specified memory image file 

(filnam.ext) into memory from the 

indicated device (dev:) and starts 
execution. 
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Command Format 



Used Under 



SAVE dev:filnam.ext areal,area2-arean 

F/B,S/J Writes the 

specified 
(filnam.ext) 
Memory is 
blocks . 



Explanation 

area(s) of user memory 
into the named file 

in save image format. 

transferred in 256-word 



SET dev : <N0> option^value 
< ' F/B,S/J 



START address 



F/B,S/J 



SUSPEND 



TIME hh:mm:ss 



UNLOAD dev, dev, . 



F/B 

(F only) 

F/B,S/J 



F/B,S/J 



Used to change device (dev:) handler 
characteristics and certain system 
configuration parameters. See Table 2-5 
(Section 2.7.2.8) for a list of options. 

Begins execution of the program 
currently in memory at the specified 
address. If an address is not 
indicated, the starting address in 
location 40 is used. 

Suspends execution of the foreground job 
currently running. 

Enters time of day in hours, minutes, 
seconds past midnight (hh:mm:ss). If all 
three arguments are omitted, the current 
time of day is output. 

Makes previously loaded handlers (dev) 
nonresident and frees the memory space 
they were using. 



B.1.2 Special Function Keys 



Key 
CTRL A 



Used Under 



F/B,S/J 



CTRL B 



F/B 



Function 

Valid when the monitor GT ON command 
has been typed and the display is in 
use. Does not echo on the terminal. 
Used after CTRL S has been typed to 
effectively page output. 

Echoes B> on the terminal and causes all 
keyboard input to be directed to the 
background job. At least one line of 
output will be taken from the background 
job (the foreground job has priority and 
control will revert to it if it has 
output) . B> does not echo if output is 
already coming from the background job. 
(Control can be redirected to the 
foreground job via CTRL F.) 
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Key 
CTRL C 



Used Under 
F/B,S/J 



CTRL E 



CTRL F 



CTRL O 



Function 

Echoes tC on the terminal,, interrupts 
current program execution,, and returns 
control to the Keyboard Monitor. If a 
program is waiting for terminal input or 
is using the device handler TT: for 
input, typing a single CTRL C interrupts 
execution and returns control to the 
monitor command level. Otherwise, two 
CTRL C's must be typed in order to 
interrupt execution. 

F/B,S/J Valid when the monitor GT ON command has 
been typed and the display is in use., 
Does not echo on the terminal, but 
causes all I/O to appear on both thcs 
display screen and the console terminal 
simultaneously. A second CTRL E 
disables console terminal output. 

Echoes F> on the terminal and directs 
all keyboard input to the foreground job 
and all output to be taken from the 
foreground job. Control remains with 
the foreground job until redirected to 
the background job (via CTRL B) or until 
the foreground job terminates. 

F/B,S/J Echoes to on the terminal and causes 
suppression of teleprinter output while 
continuing program execution. 
Teleprinter output is reenabled when one 
of the following occurs : 

1. A second CTRL is typed 



F/B 



CTRL Q 



CTRL S 



CTRL U 



CTRL Z 



2. A return to the monitor is 
indicated via CTRL C 

3. The running program issues a 
.RCTRLO directive (see 
Chapter 9) 

F/B,S/J Does not echo. Resumes printing 

characters on the terminal from the 

point at which printing was previously 
stopped (via CTRL S) . 

F/B,S/J Does not echo. Temporarily suspends 
output to the terminal until a CTRL Q is 
typed. If GT ON is in effect, each 
subsequent CTRL A causes output to 
proceed until the screen has been 
refilled once. 

F/B,S/J Echoes tU followed by a carriage return 
on the terminal and deletes the current 
input line. 

F/B,S/J Echoes tZ on the terminal and terminates 
input when used with the terminal device 
handler (TT:) . 
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Key Used Under 



RUBOUT 



Function 

F/B,S/J Deletes the last character from the 
current line. Echoes a backslash plus 
the character deleted; each succeeding 
RUBOUT deletes and echoes another 
character;, an enclosing backslash is 
printed when a key other than RUBOUT is 
typed. 



B.2 EDITOR (Chapter 3) 

B.2.1 Command Arguments 
Format 



Meaning 



n A decimal integer (in the range -16383 to +16383) which may, 
except where noted, be preceded by a + or -. Whenever an 
argument is acceptable in a command, its absence implies an 
argument of 1. 

Refers to the beginning of the current line. 

/ Refers to the end of the text in the current Text Buffer. 

= is used with the J, D and C commands only and represents -n, 
where n is equal to the length of the last text argument 
used. 



B.2. 2 Input and Output Commands 



Command 



EDIT BACKUP 



EDIT READ 



EDIT WRITE 



END FILE 



EXIT 



LIST 



Form 



Meaning 



EB devjfilnam.ext[n]$ 

Opens a file for editing, creating a 
backup copy (.BAK). 

ER dev:filnam.ext$ 

Opens a file for input. 

EW devtfilnam.ext [n] $ 

Creates a new file for output. 



EF 



EX 



(-)nL 

OL 

/L 



Closes the current output file without 
performing any further input/output 
operations . 

Outputs the remainder of the input file 
to the output file and returns control 
to the monitor. 

Prints a specified number of lines on 
the console terminal. 
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Command Form 



NEXT 



READ 



VERIFY 



WRITE 



nN 



(-)nW 

OW 

/W 



Meaning 

Outputs the contents of the Text Buffer 
to the output file, clears the buffer, 
and reads in the next page of the input 
file. 

Reads a page of text from the input file 
and appends it to the contents of the 
buffer. 

Prints the current text line (the line 
containing the pointer) on the console 
terminal. 

Outputs a specified number of lines of 
text from the Text Buffer to the output 
file. 



B.2.3 Pointer Relocation Commands 



Command 


Form 


ADVANCE 


(-)nA 

OA 

/A 


BEGINNING 


B 


JUMP 


(-)nJ 
OJ 

/J 
=J 



Meaning 

Moves the pointer over a specified 
number of lines in the Text Buffer. The 
pointer is positioned at the beginning 
of the line. 



Moves the current location pointer 
the beginning of the Text Buffer. 



to 



Moves the pointer over a specified 
number of characters in the Text Buffer., 



B.2.4 Search Commands 
Command Form 



FIND 



nFtext$ 



GET 



POSITION 



nGtext$ 



nPtext$ 



Meaning 

Beginning at the current location 
pointer, searches the entire text file 
for the nth occurrence of the specified 
character string. Pages of text are 
read into the Text Buffer, searched, and 
then written to the output file until 
the text string is found. 

Searches the contents of the Text 
Buffer, beginning at the current 
location pointer, for the next 
occurrence of the text string. 

Searches the input file for the nth 
occurrence of the text string; if the 
text string is not found, the buffer is 
cleared and a new page is read from the 
input file. 



B-6 



Command and Switch Summaries 



B.2.5 Text Modification Commands 



Command 
CHANGE 



DELETE 



EXCHANGE 



INSERT 



KILL 



Form 

(-)nCtext$ 
0Ctext$ 
/Ctext$ 

(-)nD 
OD 
/D 
=»D 

(-)nXtext$ 
0Xtext$ 
/Xtext$ 

Itext$ 



(-)nK 
OK 
/K 



Meaning 



Replaces n characters, beginning at 
the pointer, with the indicated 
text string. 

Removes a specified number of 
characters from the Text Buffer, 
beginning at the current location 
pointer. 



Replaces 
pointer, 
string. 



n lines, beginning at the 
with the indicated text 



Inserts text immediately following the 
current location pointer; an ALTMODE 
terminates the text. 



Removes n 

beginning 

pointer. 



lines from the Text Buffer 
at the current location 



B.2.6 Utility Commands 
Command Form 



EDIT CONSOLE 



EC 



EDIT DISPLAY 



ED 



EXECUTE MACRO 



nE 



Meaning 

If scroller is in use, EC returns 
scroller to its normal mode (using full 
screen for display of text and 
commands); if scroller is not in use, 
EC clears screen and returns control to 
console terminal (following ED). 

If scroller is in use, ED recalls the 
text window (following EC) and arranges 
text and commands on screen; if 
scroller is not in use, ED displays 
text window only. 

Executes the command string specified 
in the last macro command. 



MACRO 



M/command string/ 

Inserts a command string into the Macro 

Buffer. 
OM Clears the Macro Buffer and reclaims 
M// the area for text. 



SAVE 



UNSAVE 



nS 



U 



Copies the specified number of lines, 
beginning at the pointer, into the Save 
Buffer. 

Inserts the entire contents of the Save 
Buffer into the Text Buffer at the 
position of the current location 
pointer. 
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Command 
EDIT VERSION 

EDIT LOWER 

EDIT UPPER 



Form 

EV 



EL 



EU 



Meaning 

Displays the version number of 
Editor on the console terminal. 



Enables 
case. 



editing in upper- 



Returns editing to upper-case 
(after EL) . 



the 
and lower- 
only 



B.2.7 Immediate Mode Commands 

Command 

CTRL N 



CTRL G 



CTRL D 



CTRL V 



RUBOUT 



ALTMODE (two) 

(one only) 

Any character other 
than the above (with 
the exception of CTRL C) 



Meaning 

Advances the pointer (cursor) to the 
beginning of the next line. 



Moves the pointer (cursor) to 
beginning of the previous line. 



the 



Moves the pointer (cursor) forward by 
one character. 

Moves the pointer (cursor) back by one 
character. 

Deletes the character immediately 
preceding the pointer (cursor) . 

Enters Immediate Mode. 

Returns control to Editor Command Mode. 

Inserts the character as text positioned 
immediately before the pointer (cursor) . 



B.2.8 Key Commands 

Command 

ALTMODE 



CTRL C 



CTRL 



CTRL U 



Meaning 

Echoes $. A single ALTMODE terminates a 
text string. A double ALTMODE executes 
the command string. (When used alone on 
a line, two ALTMODES cause control to 
enter Immediate Mode, while a single 
ALTMODE returns control to Editor 
Command Mode . ) 

Echoes at the terminal as tC and a 
carriage return. Terminates execution 
of EDIT commands, closes any open files, 
and returns to monitor command mode. 

Echoes to and a carriage return. 
Inhibits printing on the terminal until 
completion of the current command 
string. Typing a second CTRL resumes 
output. 

Echoes tU and a carriage return. 
Deletes all the characters on the 
current terminal input line. 
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C ommand 
RUBOUT 

TAB 
CTRL X 



Meaning 
Deletes character from the current line. 

Spaces to the next tab stop. Tab stops 
are positioned every eight spaces on the 
terminal . 

Echoes tX and a carriage return. CTRL X 
causes the Editor to ignore the entire 
command string currently being entered. 
The Editor prints a <CRXLP> and an 
asterisk to indicate that the user may 
enter another command. 



B.3 PIP (Chapter 4) 



B. 3.1 Switch Summary 
Switch 
/A 



/B 
/C 

/D 
/E 

/F 
/G 



/I or no 
switch 

A 



/L 
/M:n 



Explanation 

Copies file(s) in ASCII mode; ignores nulls and 
rubouts; converts to 7-bit ASCII. 

Copies files in formatted binary mode. 

Used in conjunction with another switch; causes 
only files with current date to be included in 
the specified operation. 

Deletes file(s) from specified device. 

Lists the device directory including unused 
spaces and their sizes. Sequence numbers are 
listed for cassettes. 

Prints a short directory (filenames only) of the 
specified device. 

Ignores any input errors which occur during a 
file transfer and continues copying. 

Copies file(s) in image mode (byte by byte). 



Scans the specified device and types the absolute 
block numbers (in octal) of any bad blocks on the 
device. 

Lists the directory of the specified device. 
Sequence numbers are listed for cassettes. 

Used when I/O transfers involve either cassette 
or magtape, n represents the numeric position of 
the file to be accessed in relation to the 
physical position of the cassette or magtape on 
the drive. 
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Sv;itch Explanation 

/N:n Used with /Z to specify the number of directory 

blocks (n) to allocate to the directory. 

/0 Bootstraps the specified device (DTO, RKn, RF, 

DPn, DSn, DXn) . 

/Q Causes PIP to type each filename which is 

eligible for a wild card operation and to ask for 
a confirmation of its inclusion in the operation. 

/R Renames the specified file. 

/S Compresses the files on the specified directory 

device so that free blocks are combined into one 
area. 

/T Extends number of blocks allocated for a file. 

/U Copies the bootstrap from the specified file into 

absolute blocks and 2 of the specified device. 

/V Types the version number of the PIP program being 

used. 

/W includes the absolute starting block and any 

extra directory words in the directory listing 
for each file on the device (numbers in octal) . 
Used with /F, /L, or /E. 

/X Copies files individually (without 

concatenation) . 

/Y Causes system flies and .BAD files to be operated 

on by the command specified. 

/Z:n Zeroes (initializes) the directory of the speci- 

fied device; n is used to allocate extra words 
per directory entry. When used with /N, the 
number of directory segments for entries may be 
specified. 

B.4 MACRO/CREF (Chapter 5) 

Refer to Appendix C for a complete summary of MACRO features. CREF 
switches are also included in that appendix. 
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B.5 LINKER (Chapter 6) 

B.5.1 Switch Summary 

The Linker switches (and the command line on which each must appear) 
are: 

Switch Command 

Name Line Meaning 



/A 1st Alphabetizes the entries in the load map. 

/B:n 1st Bottom address of program is indicated as n 

(illegal for foreground links). 

/C any Continues input files on another command line 

(must be used with /0) . 

/F 1st Indicates that the Linker will use the 

default FORTRAN library, FORLIB.OBJ. 

/I 1st Includes the global symbols to be searched 

from the library. 

/L 1st Produces an output file in LDA format 

(illegal for foreground links). 

/Mzn 1st Allows terminal keyboard specification of the 

user's stack address. n represents an 
optional 6-digit unsigned octal number. 

/0:n any but Indicates that the program will be an over- 
the 1st lay structure; n specifies the overlay 
region to which the module is assigned. 

/R 1st Produces output in REL format; only files in 

REL format will run in the foreground (REL 
format files may not be run under a 
Single-Job system) . 

/S 1st Allows the maximum amount of space in memory 

to be available for the Linker's symbol 
table. (This switch should only be used when 
a particular link stream causes a symbol 
table overflow.) 

/T or 1st Transfer address is to be specified at 
/T:n terminal keyboard via n. 
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B.6 LIBRARIAN (Chapter 7) 



B.6.1 Switch Summary 

The Librarian (LIBR) switches (and the command line on which each must 
appear) are : 



Switch 
/C 

/D 
/G 

/R 

/u 



Command 
Line 

Any 



1st 
1st 

1st 
1st 



Meaning 

The command is too long for the current line 
and is continued on the next line. 

Deletes modules from a library file. 

Global deletion; deletes entry points from 
the library directory. 

Replaces modules in a library file. 

Update; inserts and replaces modules in a 
library file. 



B.7 ODT (Chapter 8) 



B.7.1 Command Summary 

In the command format shown below, r represents 
expression and n represents an octal number. 



a relocatable 



Command 


F( 


aritu 


it 


RETURN 








LINE FEED 








tor A 


t 


or 


A 


*■ or 


•«- 


or 





Explanation 

Closes open location and accepts the next 
command. 



Closes current location and 
sequential location. 

Opens previous location. 



opens next 



Indexes the contents of the opened location 
by the contents of the PC and opens the 
resulting location. 

Uses the contents of the opened location as a 
relative branch instruction and opens the 
referenced location. 

Returns to sequence prior to last @, >, or •*- 
command and opens the succeeding location. 

Uses the contents of the opened location as 
an absolute address and opens that location. 
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Command 


Format 


/ 


/ 




r/ 


\ 


\ 




r\ 


1 


I 
nl 



G 


r;G 


I 


;i 





r;0 


P 


;P 



Explanation 
Reopens the last opened location. 

Opens the word at location r. 

Reopens the last opened byte (SHIFT L) . 

Opens the byte at location r. 

After a word or byte has been opened, prints 
the address of the opened location relative 
to relocation register n. If n is omitted, 
ODT selects the relocation register whose 
contents are closest to but less than or 
equal to the address of the opened location. 

$n/ Opens general register n (0-7) . 

$B/ Opens the first word of the breakpoint table. 

$C/ Opens Constant Register. 

$F/ Opens Format Register. 

$P/ Opens Priority Register. 

$R/ Opens first Relocation Register (register 0) . 

$S/ Opens Status Register. 

rjnA Starting at location r, prints n bytes in 
their ASCII format; then inputs n bytes from 
the terminal starting at location r. 

;B Removes all Breakpoints. 

r;B Sets Breakpoint at location r. 

r;nB Sets Breakpoint n at location r. 

;nB Removes the nth Breakpoint. 

r;C Prints the value of r and stores it in the 
Constant Register. 

r;E Searches for instructions that reference 
effective address r. 

;F Fills memory words with contents of the 
Constant Register. 

Goes to location r and starts program. 

Fills memory bytes with the low-order 8 bits 
of the Constant Register. 

Calculates offset from currently open 
location to r. 

Proceeds with program execution from 
breakpoint. In single instruction mode only, 
executes next instruction. 
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Command Format Explanation 

k;P Proceeds with program execution from 
breakpoint; stops after encountering the 
breakpoint k times. In single instruction 
mode only, executes next k instructions. 

R jR Sets all Relocation Registers to -1 (highest 

address value) . 

;nR Sets Relocation Register n to -1. 

r;nR Sets Relocation Register n to the value of r. 
If n is omitted, it is assumed to be 0. 

R Selects the Relocation Register whose 
contents are closest to but less than or 
equal to contents of the opened location. 
Subtracts the contents of the register from 
the contents of the opened word and prints 
the result. 

nR Subtracts the contents of the Relocation 
Register n from the contents of the opened 
word and prints the result. 

S ;S Disables single instruction mode; reenables 

breakpoints. 

;nS Enables single instruction mode (n can have 
any value and is not significant) ; disables 
breakpoints. 

W r;W Searches for words with bit patterns which 

match r. 

X X Performs a Radix 50 unpack of the binary 

contents of the current opened word; then 
permits the storage of a new Radix 50 binary 
number in the same location. 

B.8 PROGRAMMED REQUESTS (Chapter 9) 

Appendix E summaries the programmed requests available under RT-11, 
Version 2C. 

B.9 BATCH (Chapter 12) 

Only those characters underlined need be entered. 

B.9.1 Switch Summary 

(Command Field) 



Switch 



Meaning 



/BANNER Prints header of job on the log file. 

/CRE F Specifies that a cross reference listing is 

to be produced during compilation. 

/DELE TE Indicates that input is to be deleted after 

the operation is complete. 
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Switch 



Meaning 



/DOLLARS 



/LIB RARY 
/LIS T 

/MAP 

/OBJ ECT 

/RT11 
/RUN 

/TIME 

/UNIQ UE 

/WAI T 
/WRI TE 

/NOBANN ER 

/NOCREF 

/NODELE TE 

/NODOLL ARS 
/NOLIBRARY 



Indicates that the data following this com- 
mand may have an $ in the first character 
position of a line. Reading of the data is 
terminated by one of the following BATCH 
commands: 

$JOB 

$SEQUENCE 
$EOD 
$EOJ 

or by a physical end-of-file on the BATCH 
input stream. 

Includes the default library in the link 
operation. 

Produces a temporary listing on the listing 
device (LST:) or writes data images on the 
log device (LOG:). 

Produces a temporary linkage map on the list- 
ing device (LST:). 

Produces a temporary object file as output of 
compilation or assembly. 

Sets BATCH to operate in RT-11 mode. 

Causes linking (if necessary) and execution 
of programs compiled since the last link 
and go operation or start of job. 

Writes the time of day to the log file when 
commands are executed. 

Checks for unique spelling of switches and 

keynames. 

Pauses to wait for operator action. 

Indicates that the operator is to WRITE- 
ENABLE a specified device or volume. 

Does not print a job header. 

Does not create a cross reference listing. 

Does not delete input after operation is 
complete. 

Following data may not have a $ in the first 
character position; a $ in the first character 
position signifies a BATCH control command. 

Does not include the default library in the 
link operation. 
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Switch 
/NOLIS T 
/NOMAP 
/NOOBJ ECT 

/NORTH 

/NORUN 

/NOTIM E 
/NOUNI QUE 
/NOWAI T 
/NOWRITE 



Summaries 

Meaning 

Does not produce a listing. 

Does not create MAP file. 

Does not produce object file as output of 
compilation. 

Does not set BATCH to operate in RT*11 
mode . 

Does not execute or link and execute the 
program after performing the specified command. 

Does not write time of day to log file. 

Does not check for unique spelling. 

Does not pause for operator action. 

Indicates that no writes are allowed or that 
the volume specification is read-only; the 
operator is informed and must WRITE-LOCK the 
appropriate device. 



(Specification Field) 



/BAS IC 

/EXEC UTABLE 

/FORT RAN 
/INP UT 

/LIBR ARY 

/LIS T 
/LOG ICAL 

/MAC RO 

/MAP 

/OBJ ECT 

/OUTP UT 
/PHYSICAL 



BASIC source file. 

Indicates that runnable program image file 
is to be created as the result of a link 
operation. 

FORTRAN source file. 

Input file; default if no switches are 
specified. 

Library file to be included in link operation 
(prior to default library) . 

Listing file. 

Indicates that the device is a logical device 
name. 

MACRO or EXPAND source file. 

Linker map file. 

Object file (output of assembly or compila- 
tion) . 

Output file. 

Indicates physical device name. 
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Switch Meaning 

/SOU RCE Indicates source file. 

/VID Volume identification. 



B . 9 . 2 Command Summary 

Command 

$BASIC 

$CALL 

$CHAIN 
$COPY 
$ CREATE 

$DATA 
$ DELETE 
$DIRECTORY 
$DISMOUNT 

$EOD 

$EOJ 

$FORTRAN 

$JOB 

$LIBRARY 

$LINK 
$MACRO 
$MESSAGE 
$MOUNT 

$PRINT 
$RT11 



Meaning 

Compiles a BASIC source program. 

Transfers control to another BATCH file, 
executes that BATCH file, and returns to the 
calling BATCH stream. 

Passes execution to another BATCH file. 

Copies files. 

Creates new files from data included in 
BATCH stream. 

Indicates the start of data. 

Deletes files. 

Provides a directory of the specified device. 

Signals operator to dismount a volume from a 
device and deassigns a logical device name. 

Indicates the end of data. 

Indicates the end of a job. 

Compiles a FORTRAN source program. 

Indicates the start of a job. 

Specifies library that is to be used in 
linkage operations. 

Links modules for execution. 

Assembles a MACRO source program. 

Issues message to the operator. 

Signals operator to mount a volume on a 
device and optionally assigns a logical 
device name. 

Prints files. 

Specifies that the following lines are RT-11 
mode commands . 
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Command Meaning 

Causes a program to execute. 



$RUN 

$ SEQUENCE 



Assigns an arbitrary identification number 
to a job. 



B.10 DUMP (Appendix I) 



10.1 Switch Summary 
Switch 
/B 

/Esn 
/G 
/N 

/0:n 
/S:n 
/W 
/X 



Meaning 
Outputs octal bytes. 
Ends output at block n. 
Ignores input errors. 
Suppresses ASCII output. 
Outputs only block number n. 
Starts output with block n. 
Outputs octal words. 
Outputs RAD50 characters. 



B.ll FILEX (Appendix J) 



B.ll.l Switch Summary 
Switch 
/A 



/D 

/F 



Meaning 

Indicates a character-by-character ASCII 
transfer in which rubouts and nulls are 
deleted; when /T is also used, each PDP-1.0 
word is assumed to contain five 7-bit ASCII 
bytes . 

Deletes the named file from the device; 
valid only for DOS/BATCH and RSTS DECtape. 



Causes 



'fast" listing of the device 



directory by listing filenames only. 
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Switch 
/I 



A 



/p 



Meaning 

Performs an image mode transfer; ix the 
input is either DOS/BATCH, RSTS or RT-11, 
this is a word-for-word transfer; if the 
input is from DECsystem-10 , /I indicates that 
the file resembles a file created on 
DECsystem-10 by MACY11, MACXll, or LNKXll 
with the /I switch: in this case, each 
DECsystem-10 36-bit word contains one PDP-11 
8-bit byte in its low-order bits. 

Causes a complete listing of the device 
directory, including filenames, block 
lengths, and creation dates. 

Performs a packed image transfer; if the 
input is from either DOS /BATCH, RSTS-11 or 
RT-11, this is a word-for-word transfer; if 
the input is from DECsystem-10, /P indicates 
that the file resembles a file created on 
DECsystem-10 by MACY11, MACXll, or LNKXll 
with the /P switch, in which case each 
DECsystem-10 36-bit word contains four PDP-11 
8-bit bytes aligned on bits 0, 8, 18, and 26. 
This mode is assumed if no mode switch (/A, 
/I) is indicated in a command line. 



/S 

A 

A 
/Z 



Indicates the device is a 
RSTS) file-structured device. 

Indicates the device is i 
file-structured device. 



DOS/BATCH (or 
DECsystem-10 



Types out version number of FILEX. 

Zeroes the directory of the specified device 
in the proper format (valid only for 

DOS/BATCH and RSTS DECtape) . 



B.12 SRCCOM (Appendix K) 



B . 12 . 1 Switch Summary 
Switch 
/B 



Meaning 

Compares blank lines. Without 
blank lines are ignored. 



this switch. 



/C 



/F 



Ignores comments (all text on a line preceded 
by a semicolon) and spacing (spaces and 
tabs) . 

Includes form feeds in the output file (form 
feeds are still compared if /F is not used, 
but they are not included in the output of 
differences) . 
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Command 



/H 
/L:n 

/S 



Meaning 



Types list of switches available (help text) . 

Specifies the number of lines that determine 
a match (where n is an octal number <=310) . 
The default value for n is 3. 

Ignores spaces and tabs. 



B.13 PATCH (Appendix L) 



B . 13 . 1 Command Summary 
Command 
/0 
/M 

Vr;nR 
b;B 
[s;]r,o/ 

[ss]r,o\ 

<CR> 
<LF> 



t or 



/\ 



F 

E 



Meaning 

Indicates overlay-structured file., 

Indicates monitor file. 

Sets relocation register n to value Vr. 

Sets bottom address of overlay file to b. 

Opens word location Vr + o in overlay segment 
s. 

Opens byte location Vr + o in overlay segment 
s. 

Closes currently open word/byte. 

Closes currently open word/byte and opens the 
next one. 

Closes the currently open word/byte and opens 
the previous one. 

Closes the currently open word and opens the 
word addressed by it. 

Begins patching a new file. 

Exits to RT-11 monitor. 
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B.14 PATCHO (Appendix M) 
B.14.1 Command Summary 



Command 
BYTE 

DEC 

DUMP 

EXIT 

HELP 
LIST 

OPEN 
POINT 



WORD 



Meaning 



Format ___,__. 

(#)name OP ) +) 

BYTE CSECT + OFFSET -^CSECT OR ) -(OFFSET 
NAME ( ) GLOBAL ( ) 

Modifies a given byte in an object module. 

*DEC Used when the proper checksum for the patch 
being made is unknown. PATCHO computes a 
checksum and prints out its value. 

*DUMP Prints the contents of an object module in 
octal and causes an automatic POINT to the 
next module, if any, in the input file. 

*EXIT Terminates the patch session by closing the 
file and returning control to the monitor. 

*HELP Prints an explanation of the PATCHO commands. 

*LIST Lists the names of all object modules in the 
input file in the order in which they appear 
in the file. (A POINT command should be used 
after a LIST.) 

*OPEN Opens files for input and output. 

*POINT modnam 

Locates the specified object module (modnam) 
and prepares it for subsequent WORD, BYTE, or 
DUMP operations. 



WORD 



(#)nAME OF (+ 
{% (CSECT OR j 
( I GLOBAL ( 



- (OFFSET 



CSECT + OFFSET «\%( CSECT OR 
NAME ( ) GLOBAL 

Modifies a given word in an object module. 
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C.l ASCII CHARACTER SET 



Even 

Parity 

Sit 


7-Bit 
Octal 
Code 


Character 




1 


000 
001 


NUL 
SOH 


1 


002 


STX 





003 


ETX 


1 


004 


EOT 





1 
1 


005 
006 
007 
010 


ENQ 
ACK 
BEL 
BS 






011 
012 


HT 
LP 


1 




013 
014 


VT 
FF 


1 


015 


CR 


1 


016 


SO 





017 


SI 


1 




020 
021 


DLE 
DC1 





022 


DC2 


1 


023 


DC3 





024 


DC4 


1 


025 


NAK 



Remarks 

Null, Tape Feed, CTRL SHIFT P. 

Start of Heading; also SOM (Start Of 

Message) , CTRL A. 
Start of Text; also EOA (End Of Address) , 

CTRL B. 
End of Text; also EOM (End Of Message) , 

CTRL C. 
End of Transmission (END) ; Shuts off TWX 

machines, CTRL D. 
Enquiry (ENQRY) ; also WRU, CTRL E. 
Acknowledge; also RU, CTRL F. 
Rings the Bell. CTRL G. 
Backspace; also FEO, Format Effector. 

Backspaces some machines, CTRL H. 
Horizontal TAB. CTRL I. 
Line Feed or Line Space (New Line) ; 

Advances paper to next line; duplicated 

by CTRL J. 
Vertical TAB (VTAB) . CTRL K. 
FORM FEED to top of next page (PAGE) . 

CTRL L. 
Carriage Return to beginning of line. 

Duplicated by CTRL M. 
Shift Out; Changes ribbon color to red. 

CTRL N. 
Shift In; Changes ribbon color to black. 

CTRL O. 
Data Link Escape. CTRL B (DC0) . 
Device Control 1, turns transmitter 

(reader) on, CTRL Q (X ON) . 
Device Control 2, turns punch or auxiliary 

on , CTRL R (TAPE , AUX ON) . 
Device Control 3, turns transmitter 

(reader) off, CTRL S (X OFF). 
Device Control 4, turns punch or auxiliary 

off, CTRL T (AUX OFF) . 
Negative Acknowledge; also ERR, Error, 

CTRL U. 
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Synchronous File (SYNC) , CTRL V. 

End of Transmission Block; also LEM, 

Logical End of Medium, CTRL W. 
Cancel (CANCL) , CTRL X. 
End of Medium, CTRL Y. 
Substitute, CTRL Z. 
Escape, CTRL SHIFT K. 
File Separator, CTRL SHIFT L. 
Group Separator, CTRL SHIFT M. 
Record Separator, CTRL SHIFT N„ 
Unit Separator, CTRL SHIFT 0. 
Space. 



1 


026 


SYN 





027 


ETB 





030 


CAN 


1 


031 


EM 


1 


032 


SUB 





033 


ESC 


1 


034 


FS 





035 


GS 





036 


RS 


1 


037 


US 


1 


040 


SP 





041 


I 





042 


if 


1 


043 


# 





044 


$ 


1 


045 


% 





046 


& 





047 


t 





050 


( 





051 


) 


1 


052 


* 





053 


+ 


1 


054 


t 





055 







056 


w 


1 


057 


/ 





060 





1 


061 


1 


1 


062 


2 





063 


3 


1 


064 


4 





065 


5 





066 


6 


1 


067 


7 


1 


070 


8 





071 


9 





072 


: 


1 


073 


> 





074 


< 


1 


075 


m 


1 


076 


> 





077 


? 


1 


100 


§ 





101 


A 





102 


B 


1 


103 


C 





104 


D 


1 


105 


E 


1 


106 


F 





107 


G 





110 


H 


1 


111 


I 


1 


112 


J 





113 


K 


1 


114 


L 





115 


M 





116 


N 


1 


117 


O 





120 


P 


1 


121 


Q 



Apostrophe or Acute Accent. 
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1 


122 


R 





123 


S 


1 


124 


T 





125 


U 





126 


V 


1 


127 


w 


1 


130 


X 





131 


Y 





132 


Z 


1 


133 


I 





134 


\ 


1 


135 


] 


1 


136 


t 





137 


*- 





140 


X 


1 


141 


a 


1 


142 


b 





143 


c 


1 


144 


d 





145 


e 





146 


f 


1 


147 


g 


1 


150 


h 





151 


i 





152 


j 


1 


153 


k 





154 


1 


1 


155 


m 


1 


156 


n 





157 


o 


1 


160 


P 





161 


q 





162 


r 


1 


163 


s 





164 


t 


1 


165 


u 


1 


166 


V 





167 


w 





170 


X 


1 


171 


y 


1 


172 


z 





173 


{ 


1 


174 


1 





175 


} 





176 


~ 



SHIFT K. 
SHIFT L. 
SHIFT M. 
(Appears as " 
(Appears as 
machines) . 
Accent Grave. 



on some machines) 
(Underscore) 



on 



some 



177 



DEL 



This Code Generated by ALTMODE. 

This Code Generated by PREFIX key (if 

Present) 

DELETE, RUBOUT. 



C.2 RADIX-50 CHARACTER SET 

Character ASCII Octal Equivalent 

space 40 

A-Z 101-132 



Radix- 50 Equivalent 

1-32 
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$ 44 

56 



unused 
0-9 



60-71 



33 
34 
35 
36-47 



The maximum Radix-50 value is, thus: 
2 
47*50 +47*50+47=174777 

The following table provides a convenient means of translating between 
the ASCII character set and its Radix-50 equivalents. For example, 
given the ASCII string X2B, the Radix-50 equivalent is (arithmetic is 
performed in octal) : 



x= 


'113000 










2= 


■002400 










B=> 


'000002 










X2B- 


'115402 










Single Char. 












or 


Second 


Third 


First Char. 


Character 


Character 


A 


003100 


A 


000050 


A 


000001 


B 


006200 


B 


000120 


B 


000002 


C 


011300 


C 


000170 


C 


000003 


D 


014400 


D 


000240 


D 


000004 


E 


017500 


E 


000310 


E 


000005 


F 


022600 


F 


000360 


F 


000006 


G 


025700 


G 


000430 


G 


000007 


H 


031000 


H 


000500 


H 


000010 


I 


034100 


I 


000550 


I 


000011 


J 


037200 


J 


000620 


J 


000012 


K 


042300 


K 


000670 


K 


000013 


L 


045400 


L 


000740 


L 


000014 


M 


050500 


M 


001010 


M 


000015 


N 


053600 


N 


001060 


N 


000016 





056700 





001130 





000017 


P 


062000 


P 


001200 


P 


000020 


Q 


065100 


Q 


001250 


Q 


000021 


R 


070200 


R 


001320 


R 


000022 


S 


073300 


S 


001370 


S 


000023 


T 


076400 


T 


001440 


T 


000024 


U 


101500 


U 


001510 


U 


000025 


V 


104600 


V 


001560 


V 


000026 


W 


107700 


W 


001630 


W 


000027 


X 


113000 


X 


001700 


X 


000030 


Y 


116100 


Y 


001750 


Y 


000031 


Z 


121200 


Z 


002020 


Z 


000032 


$ 


124300 


$ 


002070 


$ 


000033 


* 


127400 


• 


002140 


• 


000034 




132500 




002210 




000035 





1356 00 





002260 





000036 


1 


140700 


1 


002330 


1 


000037 


2 


144000 


2 


002400 


2 


000040 
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3 


147100 


3 


002450 


3 


000041 


4 


152200 


4 


002520 


4 


000042 


5 


155300 


5 


002570 


5 


000043 


6 


160400 


6 


002640 


6 


000044 


7 


163500 


7 


002710 


7 


000045 


8 


166600 


8 


002760 


8 


000046 


9 


171700 


9 


003030 


9 


000047 



C„3 MACRO SPECIAL CHARACTERS 
Character Function 



form feed 
line feed 
carriage return 
vertical tab 



% 
tab 



space 

# 

@ 

( 

) 



* 
/ 

& 

I 



(comma) 



• (apostrophe) 

< 

> 
t 
t 

\ 



Source line terminator, forces a new listing page 

Source line terminator 

Formatting character 

Source line terminator 

Label terminator 

Direct assignment indicator 

Register term indicator 

Item terminator, field terminator 

Item terminator, field terminator 

Immediate expression Indicator 

Deferred addressing indicator 

Initial register indicator 

Terminal register indicator 

Operand field separator 

Comment field indicator 

Arithmetic addition operator or autoincrement 

indicator 
Arithmetic subtraction operator or autodecrement 

indicator 
Arithmetic multiplication operator 
Arithmetic division operator 
Logical AND operator 
Logical OR operator 
Double ASCII character indicator 
Single ASCII character indicator 
Assembly location counter 
Initial argument indicator 
Terminal argument indicator 
Universal unary operator 
Argument indicator 
MACRO numeric argument indicator 



C„4 ADDRESS MODE SYNTAX 

In the following syntax table, n represents an integer between and 
7? R is a register expression; E represents any expression; ER 
represents either a register expression or an absolute expression in 
the range to 7. 



On Register 

In Deferred Register 



R Register R contains the operand. 
R is a register expression. 

@R or (R) Register R contains the operand 
address. 
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2n Autoincrement 



Deferred 
3n Autoincrement 



4n Autodecrement 



Deferred 
5n Autodecrement 



Index by the 
Register 
6n Specified 



(ER) + 



@ (ER) + 



-(ER) 



§- (ER) 



E(ER) 



7n 


Deferred index 
by the Register 
Specified 


@EC 


27 


Immediate Operand 


#E 


37 


Absolute address 


@#E 


67 


Relative address 


E 


77 


Deferred relative 
address 


@E 



The contents of the register 
specified by ER are incremented 
after being used as the address 
of the operand. 



ER contains a pointer to the 
address of the operand. ER is 
incremented after use. 

The contents of register ER are 
decremented before being used as 
the address of the operand. 



The contents of register ER are 

decremented before being used eis 

a pointer to the address of the 
operand. 



The value obtained when E is 
combined with the contents of 
the register specified (ER) is 
the address of the operand. 



E added to ER produces a pointer 
to the address of the operand. 

E is the operand. 

E is the operand address. 

E is the address of the operand. 



E is a pointer to the address of 
the operand. 



C.5 INSTRUCTIONS 

The tables of instructions which follow are grouped according to the 
operands they take and according to the bit patterns of their 
op- codes . 



The following symbols are used to indicate the instruction type 
format : 

OP Instruction mnemonic 

R Register Expression 

E Expression 

ER Register expression or expression 

0<=ER<»7 

AC Floating point register expression 

A General address specification 
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In the representation of op-codes, the following symbols are used: 

SS Source operand Specified by a 6-bit 

address mode 

DD Destination Specified by a 6-bit 
operand address mode 

XX 8-bit offset to a Branch instructions 
location 

R Integer between Represents a general 
and 7 register 

Symbols used in the description of instruction operations aret 

SE Source Effective Address 

FSE Floating Source Effective Address 

DE Destination Effective Address 

FDE Floating Destination Effective Address 

I I Absolute Value of 

( ) Contents of 

-»■ Becomes 

The condition codes in the processor status word (PS) are affected by 
the instructions; these condition codes are represented as follows: 

N Negative bit: Set if the result is negative 

Z Zero bit: Set if the result is zero 

V Overflow bit: Set if the operation caused an 

overflow 
C Carry bit: Set if the operation caused a 

carry 

In the representation of the instruction's effect on the condition 
codes, the following symbols are used: 

* Conditionally set 
Not affected 

Cleared 

1 Set 

To set conditionally means to use the instruction's result to 
determine the state of the code. 

Logical operators are represented by the following symbols: 



I 


Inclusive OR 


© 


Exclusive OR 


& 


AND 



Used over a symbol to represent 
the l's complement of the symbol 
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C.5.1 ] 


Double Operand 


Instructions 


(OP 


A,A) 










Op-Code 


Mnemonic 


Stands for 


Operation 




Status Word 

Condition 

Codes 

N Z V C 


OlSSDD 
IISSDD 


MOV 
MOVB 


MOVe 
MOVe Byte 


(SE) 


-+ (DE) 




* 


* 


- 


02SSDD 
12SSDD 


CMP 
CMPB 


CoMPare 
CoMPare Byte 


(SE)- 


-(DE) 




* 


* 


* * 


03SSDD 
13SSDD 


BIT 
BITB 


Bit Test 

Bit Test Byte 


(SE) 


& (DE) 




* 


* 


- 


04SSDD 
14SSDD 


BIC 
BICB 


Bit Clear 

Bit Clear Byte 


(SE) 


& (DE) 


-> (DE) 


* 


* 


- 


05SSDD 
15SSDD 


BIS 
BISB 


Bit Set 

Bit Set Byte 


(SE) 


1 (DE) 


->■ (DE) 


* 


* 


- 


06SSDD 
16SSDD 


ADD 
SUB 


ADD 
SUBtract 


(SE) 
(DE) 


+ (DE) 
- (SE) 


■* (DE) 

•*■ (DE) 


* 
* 


* 
* 


* * 

* * 



C.5.2 Single Operand Instructions 



(OP A) 



Op-code 


Mnemonic 


Stands for 


Operation 


Status Word 

Condition 

Codes 

N Z V C 


0050DD 
1050DD 


CLR 
CLRB 


CLeaR 
CLeaR Byte 


-+ (DE) 





1 





0051DD 
1051DD 


COM 
COMB 


COMplement 
COMplement Byte 


(DE) 


•* (DE) 


* 


* 


1 


0052DD 
1052DD 


INC 
INCB 


INCrement 
INCrement Byte 


(DE) 


+ 1 -»■ (DE) 


* 


* 


* 1 


0053DD 
1053DD 


DEC 
DECB 


DECrement 
DECrement Byte 


(DE) 


- 1 -*- (DE) 


* 


* 


* - 


0054DD 
1054DD 


NEG 
NEGB 


NEGate 
NEGate Byte 


(DE) 


+ 1 ■*■ (DE) 


* 


* 


* * 


0055DD 
1055DD 


ADC 
ADCB 


ADd Carry 

ADd Carry Byte 


(DE) 


+ (C) •+ (DE) 


* 


* 


* * 


0056DD 
1056DD 


SBC 
SBCB 


SuBtract Carry 
SuBtract Carry 
Byte 


(DE) 


- (C) ■+ (DE) 


* 


* 


* * 


0057DD 
1057DD 


TST 
TSTB 


TeST 
TeST Byte 


(DE) 




* 


* 
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C.5.3 Rotate/Shift 



Op-Code Mnemonic Stands for 



Operation 



006 ODD ROR 

106 ODD RORB 

0061DD ROL 

1061DD ROLB 

0062DD ASR 

1062DD ASRB 

0063DD ASL 

1063DD AS LB 

0001DD JMP 

0003DD SWAB 



ROtate Right EH^i 



ROtate Right C 
Byte L 



-Eh 



ROtate Left m- c 



■ ■ i ■ ■ ' 



ROtate Left C 
Byte 

Arithmetic 
Shift Right ^C 



-El- 



<n- 



I i~ I , , I , , I 



IHE- 



Arithmetic 
Shift Right j-EI 
Byte 






DHS 



Arithmetic EHI 
Shift Left 



>• 



Arithmetic H- C 
Shift Left 
Byte 



jump 

SWAp Bytes 



>e-ez 



Status Word 

Condition 

Codes 

N Z V C 

* * * * 

* * * * 



* * * * 

* * * * 

* * * * 

* * * * 

* # * * 

* * * * 



DE -MPC) 



* * 



The following instructions are available on the PDP-11/03 (LSI/11) 

only: 

Status Word 

Condition 

Codes 

N Z V C 



Op-Code Mnemonic Stands for 



Operation 



1067DD MFPS 



1064SS MTPS 



Move byte From (DE)+-PSW 

Processor Status 

word 



* * - 



* * * * 



Move byte To (SE)->-PSW 
Processor Status 
word 
The following instructions are available on the PDP-11/35,40,45 as 
noted : 

status Word 
Condition 
Codes 
Op-Code Mnemonic Stands for Operation N Z V C 



11/35, 11/40, 11/45 with KT11 
0065SS MFPI 



Move From 
Previous 
Instruction 
space 



(SB) + (TEMP) 
(SP)-2 + (SP) 
(TEMP) ■*■ ( (SP) ) 



* * - 
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11/45 with KT11 only 



1065SS MFPD 


Move From 


(SE) ■+ (TEMP) 




Previous 


(SP)-2->- 


(SP) 




Data space 


(TEMP) ■*■ 


( (SP) ) 


11/35, 11/40, 11/45 with KT11 


( (SP) ) * 




0066DD MTPI 


Move To 


(TEMP) 




Previous 


(SP+2) -v 


(SP) 




Instruction 


(TEMP) -»• 


(DE) 




space 






11/45 with KT11 only 








106 6DD MTPD 


Move To 


( (SP) ) * 


(TEMP) 




Previous 


(SP+2) ->- 


(SP) 




Data space 


(TEMP) ■* 


(DE) 


170 1DD LDFPS 


Load FPP 
program status 


DE ■*■ FPS 




11/35, 11/40, 11/45 









0067DD 



SXT 



Sign eXTend 



11/45 with FP11-B 



0707DD 


NEGD 


0707DD 


NEGF 


1702DD 


STFPS 


1703DD 


STST 


1704DD 


CLRD 


1704DD 


CLRF 


1705DD 


TSTD 


1705DD 


TSTF 


1706DD 


ABSD 



1706DD 



ABSF 



NEGate Double 

NEGate Floating 

STore Floating 
Point processor j 
program Status 

STore floating 
point processor; 
STatus 

CLeaR Double 

CLeaR Floating 

TeST Double 

TeST Floating 

make ABSolute 
Double 

make ABSolute 
Floating 



-f DE if N bit 
is clear 
-1 + DE if N bit 
is set 



-(FDE) ->-FDE 
- (FDE) + FDE 



See Chapter 7 
in PDP-11/ 45 
Processor 
Handbook 



■*■ (FDE) 
-»■ (FDE) 
(FDE) 
(FDE) 
|(FDE)| +{FDE) 

| (FDE)| ->-(FDE) 



- 



* * - 



* * o - 



_ * _ - 



* * 



10 
10 

* * 

* * 
0*00 



January 1976 
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C.5.4 Operate Instructions (OP) 



Op-Code Mnemonic Stands for 



000000 HALT 



00001 WAIT 



000002 



RTI 



HALT 



WAIT 



ReTurn from 
Interrupt 
(Return from 
Trap) 



Operation 



Status Word 

Condition 

Codes 

N Z V C 



The computer stops - - - - 
all functions. 

The computer stops - - - - 

and waits for an 

interrupt. 

The PC and ST are * * * * 

popped off the SP 

stack: 

( (SP) ) ■* (PC) 

(SP)+2 + (SP) 

((SP)) + (ST) 

(SP)+2 -»• (SP) 



000005 


RESET 


RESET 


Returns 
devices 
power-on 


all I/O 

to 

i state. 










000241 


CLC 


CLear Carry bit 


-*-C 






- 


- 


- 





000261 


SEC 


SEt Carry bit 


1 ->C 






- 


- 


- 


1 


000242 


CLV 


CLear overflow 


->-V 






- 


- 





- 


000262 


SEV 


SEt overflow 
bit 


1 -+-V 






- 


- 


1 


- 


000244 


CLZ 


CLear Zero bit 


■*■ Z 






- 





- 


- 


000264 


SEZ 


SEt Zero bit 


1 ->z 






- 


1 


- 


- 


000250 


CLN 


CLear Negative 
bit 


+ N 









- 


- 


- 


000270 


SEN 


SEt Negative 
bit 


1 -+-N 






1 


- 


- 


- 


000257 


CCC 


Clear all 
Condition 
Codes 


+N 

-»■ Z 
+V 
+ C 


















000277 


sec 


Set all 

Condition 

Codes 


.1 +N 
1 + Z 
1+V 

1 -*c 






1 


1 


1 


1 



000240 



NOP 



No operation 



C-ll 



MACRO Assembler, Instruction, and Character Code Summaries 

The following instructions are available on the PDP-11/45 with FP11-B 
only: 



Op-Code Mnemonic Stands for 



170000 



CFCC 



Copy Floating 
Condition Code 



Operation 

Copy FPP 
condition codes 
into CPU condi- 
tion codes. 



Status Word 

Condition 

Codes 

N Z V C 



170011 



170001 



SETD 



SETF 



SET Double 

floating 

mode 

SET Floating 
mode 



FPP set to 

double 

precision 

FPP set to 

single 

precision 

mode 



170002 



SETI 



SET Integer 
mode 



FPP set for 
integer data 
(16 bits) 



170012 



SETL 



SET Long 
integer mode 



FPP set for 
long integer 
data (32 bits) 



All 11/45" s, with and without FP11-B 



000006 



RTT 



ReTurn from 
inTerrupt 



Same as RTI 
instruction but 
inhibits trace 
trap 



C.5.5 Trap Instructions (OP or OP e where 0<=E<=377 (8) ) 

*(OP (only)) 



Op-Code Mnemonic Stands for 



*000003 BPT 



Breakpoint 
Trap 



Operation 

Trap to 
location 14. 
This is used 
to call ODT. 



Status Word 

Condition 

Codes 

N Z V C 



♦000004 IOT 



Input Output 
Trap 



Trap to 
location 20. 
This is used 
to call IOX. 
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104000- 
104377 



104400- 
104777 



EMT 



TRAP 



EMulator 


Trap to 


Trap 


location 30. 




This is used 




to call system 




programs . 


TRAP 


Trap to 




location 34. 




This is used 




to call any 




routine desired 




by the programmer 



C.5.6 Branch Instructions OP E 

(where -128 (decimal) < (E-.-2) /2<127 (decimal) ) 



Op-Code Mnemonic 



0004XX 
0010XX 
014XX 
0020XX 

0024XX 
0030XX 

0034XX 



BR 
BNE 
BEQ 
BGE 

BLT 
BGT 

BLE 



1000XX 


BPL 


1004XX 


BMI 


1010XX 


BHI 


1014XX 


BLOS 


1020XX 


BVC 


1024XX 


BVS 


1030XX 


BCC (or 




BHIS) 


1034XX 


BCS (or 




BLO) 



Stands for 

BRanch always 

Branch if Not Equal (to zero) 

Branch if EQual (to zero) 

Branch if Greater than or 
Equal (to zero) 

Branch if Less Than (zero) 

Branch if Greater Than 
(zero) 

Branch if Less than or 
Equal (to zero) 

Branch if PLus 

Branch if Minus 

Branch if Higher 

Branch if LOwer or Same 

Branch if overflow Clear 

Branch if overflow Set 

Branch if Carry Clear 

(or Branch if High or Same) 

Branch if Carry Set (or 
Branch if LOw) 



Condition to be 
met if branch is 
to occur 



Z-0 
Z-l 
N® V-0 

N(J) V - 1 
Z I (N © V) =0 

Z I (N ® V) -1 

N-0 
N-l 

C(T) Z-0 
CI Z-l 
V-0 
V-l 

C-0 

C-l 



C-13 



MACRO Assembler, Instruction, and Character Code Summaries 



C.5.7 Register Destination (OP ER,A) 



Op-Code Mnemonic Stands for 



004RDD 



JSR 



Jump to 
Sub Routine 



Operation 

Push register 
on the SP stack, 
put the PC in 
the register: 

DE TEMP (TEMP- 
temporary storage 
register internal 
to processor.) 



Status Word 

Condition 

Codes 

N Z V C 



(SP)-2 -*-SP 
(REG) ->- (SP) 
(PC) -»■ REG 
(TEMP) -f PC 

The following instruction is available only on the 11/35, 11/40, 
11/45: 



074RDD 



XOR 



exclusive OR (R) (7) (DE) ->- (DE) 



C.5.8 Register-Offset (OP R,E) 

The following instruction is available only on the PDP-11/35, 11/40, 
11/45: 



Op-Code Mnemonic Stands for 



077RDD 



SOB 



Subtract One 
and Branch 



Operation 

<R)-1+(R) 
(PC)-(2*DE) 



(PC) 



N Z V C 



C.5.9 Subroutine Return (OP ER) 
Op-Code Mnemonic Stands for 



00020R 



RTS 



ReTurn from 
Subroutine 



Operation 

Put register 
in PC and pop 
old contents from 
SP stack into 
register. 



N Z V C 
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C.5.10 Source- Register (OP A,R) 

The following instructions are available on the 11/35, 11/40, 11/45 
only: 

Status Word 
Floating 
Condition 
Codes 
Operation N z V C 



Op-Code Mnemonic Stands for 



071RSS DIV 
070RSS MUL 
072RSS ASH 



Divide 
MULtiply 



Arithmetic 
SHift 



(R),(Rll)/(SRC) ■* (R),(R11) 

* * * * 



(R)*(SRC) + (R),(R11) 



* * * * 



R is shifted 
according to 
low-order 6-bits 
of source 



•H 



or 



m-i 



073RSS 



ASHC 



Arithmetic 

SHift 

Combined 



R,RVL are shifted 
according to low- 
order 6 bits of 
source 



* * * * 









1* 


-l f , . . 




. , , . J-M 


or 


I'M , . . , . .i-r- ,..,.. 1 


r ' 


-E^ 


1 , , I 7 "7 l 


. , . . h- 



C.5.11 Floating-Point Source Double Register (OP A, AC) 

The following instructions are available on the PDP-11/45 with FPll-B 
only t 

Status Word 

Floating 

Condition 

Codes 

FN FZ FV FC 



Op-Code Mnemonic Stands for Operation 



172(AC)SS ADDD 



ADD Double (FSE) + (AC) ->- (AC) * 
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172(AC)SS ADDP 



ADD Floating (FSE) +(AC) ->- (AC) * * * 



173(AC+4)SS 

CMPD 


CoMPare 
Double 


173(AC+4)SS 

CMPF 


CoMPare 
Floating 


174(AC+4)SS 

DIVD 


Divide 
Double 


174(AC+4)SS 

DIVF 


Divide 
Floating 


177(AC+4)SS 

LDCDF 


LoaD and 



177(AC+4)SS 

LDCFD 



172(AC+4)SS 

LDD 

172(AC+4)SS 

LDF 

171(AC+4)SS 

MODD 



(FSE) - (AC) 



(FSE) -(AC) 



(AC) /(FSE) ->- (AC) 



(AC) /(FSE) ■* (AC) 



vert from 
Double to 
Floating 



LoaD and Con- (FSE) ■+■ (AC) 
vert from 
Floating to 
Double 



LoaD Double (FSE) ■* (AC) 



LoaD Floating (FSE) -»■ (AC) 



Multiply and 

integerize (AC) * (FSE) ■*■ (AC) , (AC1) 

double * * 







* * 







171(AC+4)SS 

MODF 



171(AC)SS MULD 
171(AC)SS MULF 
173(AC)SS SUBD 
173(AC)SS SUBF 



Multiply and (AC) * (FSE) ■+ (AC) 
integerize 
floating- 
point 



MULtiply 
Double 

MULtiply 
Floating 

SUBtract 
Double 

SUBtract 
Floating 



(AC) * (FSE) ■*■ (AC) 
(AC)* (FSE) + (AC) 
(FSE) -(AC)-* (AC) 
(FSE) -(AC)* (AC) 



* * 

* * 

* * 

* * 
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C.5.12 Source-Double Register (OP A, AC) 

The following instructions are available on the PDP-11/45 with FP11-B 
only: 



Op-Code Mnemonic Stands for Operation 



177(AC)SS LDCID 



LoaD and Con- (SE) ■*■ (AC) 
vert Integer 
to Double 



Status Word 
Condition Codes 
FN FZ FV FC 



177(AC)SS LDCIF 



177(AC)SS LDCLD 



LoaD and Con- (SE) ->- (AC) 
vert Integer 
to Floating 

LoaD and Con- (SE) -v (AC) 
vert Long 
integer to 
Double 



177(AC)SS LDCLF 



176(AC+4)SS 

LDEXP 



LoaD and Con- (SE) ■*■ (AC) 
vert Long In- 
teger to 
Floating 



LoaD EXPonent (SE)+200 ->■ (AC EXP) * 



C.5.13 Double Register-Destination (OP AC, A) 

The following instructions are available on the PDP-11/45 with FP11-B 
only: 



Op-Code Mnemonic Stands for Operation 



176(AC)DD STCFD 



STore, Con- 
vert from 
Floating to 
Double 



(AC) ■* (FDE) 



Status Word 
Condition Codes 
FN FZ FV FC 



176(AC)DD STCDF 



STore, Con- 
vert from 
Double to 
Floating 



175(AC+4)DD 

STCDI(l) STore, Con- 
vert from 
Double to 
Integer 



(AC) -► (FDE) 



(AC) ■*■ (FDE) 



(1) These instructions set both the floating-point and processor 
condition codes as indicated. 
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175(AC+4)DD 

STCDL(l) STore, Con- (AC) -*- (FDE) * 
vert from 
Double to 
Long integer 

175(AC+4)DD 

STCFI(l) STore, Con- (AC) -*- (FDE) * 
vert from 
Floating to 
Integer 

174 (AC+4) DD 

STCFL(l) STore, Con- (AC)* (FDE) * 
vert from 
Floating to 
Long integer 

174 (AC) DD STD STore Double (AC) ■*■ (FDE) 

174(AC)DD STF STore (AC) -* (FDE) 

Floating 

175(AC)DD STEXP(l) STore (AC EXP)-200 * (DE) * 

EXPonent 



C.5.14 Number 

The following instruction is available on the 11/35, 11/40, 11/45 
only j 

Status Word 
Condition Codes 
Op-Code Mnemonic Stands for Operation N Z V C 

064NN MARK MARK Stack cleanup on - - - - 

return from sub- 
routine. 



C.5.15 Priority 

The following instruction is available on the PDP-11/45 only: 

Status Word 
Condition 
Codes 
Op-Code Mnemonic Stands for Operations N Z V C 

00023N SPL Set Priority (X) * (PS) - - - - 

Level (bits 7-5) 



(1) These instructions set both the floating-point and processor 
condition codes as indicated. 
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C.6 ASSEMBLER DIRECTIVES 



Form 



Described in 
Manual Section 



Operation 



5.5.3.3 



tBn 

ten 
tDn 

tPn 
ton 



5*6 • 3 • 3 

5.5.4.2 

5.5.6.2 
5.5.4.2 

5.5.6.2 
5.5.4.2 



.ASCII string 5.5.3.4 



.ASCIZ string 5.5.3.5 



ASECT 


5.5.9 


BLKB exp 


3 » U # -U * J 


BLKW exp 


5.5.5.3 



A single quote character (apostrophe) 
followed by one ASCII character 
generates a word containing the 7-bit 
ASCII representation of the character 
in the low-order byte and zero in the 
high-order byte. 

A double quote character followed by 
two ASCII characters generates a word 
containing the 7-bit ASCII 
representation of the two characters. 

A backslash preceding an argument 
causes the number to be treated in the 
current radix. 

Temporary radix control; causes the 
number n to be treated as a binary 
number. 

Creates a word containing the one's 
complement of n. 

Temporary radix control; causes the 
number n to be treated as a decimal 
number. 

Creates a one-word floating point 
quantity to represent n. 

Temporary radix control; causes the 
number n to be treated as an octal 
number. 

Generates a block of data containing 
the ASCII equivalent of the character 
string (enclosed in delimiting 
characters) one character per byte. 

Generates a block of data containing 
the ASCII equivalent of the character 
string (enclosed in delimiting 
characters) one character per byte 
with a zero byte following the 
specified string. 

Begin or resume absolute section. 

Reserves a block of storage space exp 
bytes long. 

Reserves a block of storage space exp 
words long. 
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.BYTE expl, 

exp2 , . . . 



5.5.3.1 



.CSECT symbol 5.5.9 



.DSABL arg 
.ENABL arg 



.END 
.END exp 



.ENDC 



.ENDM 

.ENDM symbol 



.EOT 



5.5.2 
5.5.2 
5.5.7.1 

5.5.11 
5.6.1.2 



5.5.7.2 



.ERROR exp, string 5.6.5 



.EVEN 



,FLT2 argl, 
arg2 , • • • 



,FLT4 argl, 
arg2 , • • • 



5.5.5.1 



5.5.6.1 



5.5.6.1 



.GLOBL syml, 5.5.10 
sym2 , . • . 

.IDENT symbol 5.5.1.5 



, IF cond, 
arguments 



5.5.11 



Generates successive bytes of data 
containing the octal equivalent of the 
expression (s) specified. 

Begins or resumes named or unnamed 
relocatable section. 

Disables the assembler function 
specified by the argument. 

Provides the assembler function 
specified by the argument. 

Indicates the physical end of the 
source program. An optional argument 
specifies the transfer address. 



Indicates 
block. 



the end of a condition 



Indicates the end of the current, 
repeat block, indefinite repeat block, 
or macro. The optional symbol, if: 
used, must be identical to the macro 
name. 

Ignored. Indicates End-of-Tape which 
is detected automatically by the 
hardware. 

Causes a text string to be output to 
the listing containing the optional 
expression specified and the indicated 
text string. The line will be flagged 
with the "P" error code. 

Ensures that the assembly location 
counter contains an even address by 
adding 1 if it is odd. 

Generates successive two-word float- 
ing point equivalents for the 
floating-point numbers specified as 
arguments . 

Generates successive four-word float- 
ing point equivalents for the 
floating-point numbers specified as 
arguments . 



Defines the symbol (s) 
global symbol (s) . 



specified as 



Provides a means of labeling the 
object module produced as a result of 
assembly. This directive is not 
supported by RT-11, but is included 
for compatibility with other systems. 

Begins a conditional block of source 
code which is included in the assembly 
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.IFF 



• IFT 



,IFTF 



5.5.11.1 



5.5.11.1 



5.5.11.1 



,IIF cond,arg, 5.5.11.2 
statement 



,IRP sym, 5.6.6 
<argl,arg2,...> 



.IRPC sym, string 5.6.6 



.LIMIT 



.LIST 
.LIST arg 



5.5.8 



5.5.1.1 



.MACRO sym,argl, 5.6.1.1 
argl f ... 



.MCALL 



.MEXIT 



5.6.8 



5.6.1.3 



only if the 
with respect 
specified. 



stated condition is met 
to the argument (s) 



Appears only within a conditional 
block and indicates the beginning of a 
section of code to be assembled if the 
condition tested false. 

Appears only within a conditional 
block and indicates the beginning of a 
section of code to be assembled if the 
condition tested true. 

Appears only within a conditional 
block and indicates the beginning of a 
section of code to be unconditionally 
assembled. 

Acts as a one-line conditional block 
where the condition is tested for the 
argument specified. The statement is 
assembled only if the condition tests 
true. 

Indicates the beginning of an indef- 
inite repeat block in which the 
symbol specified is replaced with 
successive elements of the real 
argument list (which is enclosed in 
angle brackets) . 

Indicates the beginning of an 
indefinite repeat block in which the 
symbol specified takes on the value of 
successive characters in the character 
string. 

Reserves two words into which the 
Linker inserts the low and high 
addresses of the relocated code. 

Without an argument, .LIST increments 
the listing level count by 1. With an 
argument, .LIST does not alter the 
listing level count but formats the 
assembly listing according to the 
argument specified. 

Indicates the start of a macro with 
the specified name containing the 
dummy arguments specified. 

Used to specify the names of all 
system macro definitions not defined 
in the current program but required by 
the program. 



Causes an exit from the current 
or indefinite repeat block. 



macro 
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.NARG symbol 



5.6.4 



,NCHR sym,<string>5.6.4 



.NLIST 
.NLIST arg 



5.5.1.1 



.NTYPE symbol, arg 5.6.4 



.ODD 



.PAGE 



5.5.5.2 



5.5.1.6 



.PRINT exp, string 5.6.5 



.RADIX n 



5.5.4.1 



.RAD50 string 5.5.3.6 



,REPT exp 



5.6.7 



.SBTTL string 5.5.1.4 



.TITLE string 5.5.1.3 



Appears only within a macro definition 
and equates the specified symbol to 
the number of arguments in the macro 
call currently being expanded. 

Can appear anywhere in a source 
program; equates the symbol specified 
to the number of characters in the 
string (enclosed in delimiting 
characters) . 

Without an argument, .NLIST decrements 
the listing level count by 1. With an 
argument, .NLIST deletes the portion 
of the listing indicated by the 
argument. 

Appears only in a macro definition and 
equates the low-order six bits of the 
symbol specified to the six-bit 
addressing mode of the argument. 

Ensures that the assembly location 
counter contains an odd address by 
adding 1 if it is even. 

Causes the assembly listing to skip to 
the top of the next page. 

Causes a text string to be output to 
the listing containing the optional 
expression specified and the indicated 
text string. 

Alters the current program radix to n, 
where n can be 2, 4, 8, or 10. 

Generates a block of data containing 
the Radix-50 equivalent of the 
character string (enclosed in 
delimiting characters) . 

Begins a repeat block. Causes the 
section of code up to the next .ENDM 
or .ENDR to be repeated exp times. 

Causes the string to be printed as 
part of the assembly listing page 
header. The string part of each 
.SBTTL directive is collected into a 
table of contents at the beginning of 
the assembly listing. 

Assigns the first symbolic name in the 
string to the object module and causes 
the string to appear on each page of 
the assembly listing. One .TITLE 
directive should be issued per 
program. 



C-22 



MACRO Assembler, Instruction, and Character Code Summaries 

.WORD expl, 5.5.3.2 Generates successive words of data 
exp2 , . . . containing the octal equivalent of the 

expression (s) specified. 

C.7 MACRO/CREF SWITCHES 



C.7.1 Listing Control Switches 

Switch Meaning 

/L:arg These switches are used to control listing output. 
/N:arg Arguments which are valid for either switch include: 

Arg Controls Listing of: 

SEQ Source line sequence numbers 

LOC Location counter 

BIN Generated binary code 

BEX Binary extensions 

SRC Source code 

COM Comments 

MD Macro definitions and repeat range definitions 

MC Macro calls and repeat range expansions 

ME Macro expansions 

MEB Macro expansion binary code 

CND Unsatisfied conditions and all .IF 

and .ENDC statements. 

LD Listing directives having no arguments 

TOC Table of contents 

TTM Listing output format 

SYM Symbol table 

<no arg> /N with no argument causes only table of contents, 

symbol table, and error listings to be produced. 

/L with no argument causes .LIST and .NLIST 
directives without arguments which appear in the 
source program to be ignored. 

C.7. 2 Function Control Switches 

Switch Meaning 

/D:arg These switches are used to enable or disable certain 
/E:arg functions in source input files. Valid arguments 
include : 

Arg Enables or Disables; 

ABS Absolute binary output 

AMA Assembly of all absolute addresses as relative 

addresses 
CDR Source columns 73 and greater to be treated as 

comments 
FPT Floating point truncation 

LC Accepts lower case ASCII input 

LSB Local symbol block 

PNC Binary output 
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C.7.3 CREF Switches 

Switch Produces Cross-Reference of: 



/CiS 


User-defined symbols 


/C:R 


Register symbols 


/C:M 


MACRO symbolic names 


/C:P 


Permanent symbols 


/C:C 


Control sections 


/C:E 


Error codes 


/C:<no arg> 


Equivalent to /C:S:M:E 
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C.8 OCTAL-DECIMAL CONVERSIONS 



oooo 

to 
0777 
(Octal) 



Octal 

10000 

20000 

30000 

40000 

50000 

60000 

70000 



0000 

to 

0511 

(Decimal) 



Decimal 
4096 
8192 
12288 
16384 
20480 
24576 
28672 



1000 

to 

1777 

(Octal) 



0512 

to 

1023 

(Decimal) 








1 


2 


3 


4 


5 


6 


7 







I 


2 


1 


4 


i 


6 7 


0000 


0000 


0001 


0002 


0003 


0004 


0005 


0006 


0007 


0400 


0256 


0257 


0258 


0259 


0260 


0261 


0262 0261 


0010 


0008 


0009 


0010 


0011 


0012 


0013 


0014 


0015 


0410 


0264 


0265 


0266 


0267 


0268 


0269 


0270 0271 


0020 


0016 


0017 


0011 


0019 


0020 


0021 


0022 


0023 


0420 


0272 


0273 


0274 


0275 


0276 


0277 


0278 0279 


0030 


0024 


002S 


0026 


0027 


0028 


0029 


0030 


0031 


04 30 


0260 


0261 


0282 


0263 


02B4 


0285 


0266 0287 


0040 


0032 


0033 


0034 


0035 


0036 


0037 


0038 


0039 


0440 


0268 


0289 


0290 


0291 


0232 


0291 


0294 0295 


0050 


0040 


0041 


0042 


0043 


0044 


0045 


0046 


0047 


0450 


0296 


0297 


0296 


0299 


0300 


0301 


0302 0303 


0060 


0048 


0049 


0050 


0051 


0052 


0053 


0054 


0055 


0460 


0304 


0305 


0306 


0307 


0308 


0309 


0310 0311 


0070 


0056 


0057 


0058 


0059 


0060 


0061 


0062 


0063 


0470 


0312 


0313 


03I4 


0315 


0316 


0317 


0316 0319 


0100 


0064 


0065 


0066 


0067 


0068 


0069 


0070 


0071 


0500 


0320 


032I 


0322 


0323 


0324 


0325 


0326 0327 


0110 


0072 


0073 


0074 


0075 


0076 


0077 


0078 


0079 


0510 


0328 


0329 


0330 


0331 


0332 


0333 


0334 0335 


0120 


0080 


0081 


0082 


0083 


0084 


0085 


0086 


0087 


0520 


0336 


0337 


0338 


0339 


0340 


0341 


0342 0343 


0130 


0088 


0089 


0090 


0091 


0092 


0093 


0094 


0095 


0520 


0344 


0345 


0346 


0347 


0348 


0349 


0350 0351 


OHO 


0096 


0097 


0096 


0099 


0100 


0101 


0102 


0103 


0540 


0352 


0353 


0354 


0355 


0356 


0357 


0356 0359 


0150 


0104 


0105 


0106 


0107 


0108 


0109 


0110 


0111 


0550 


0360 


036 1 


0362 


0363 


0364 


0365 


0366 0367 


0190 


0112 


0113 


0114 


0115 


0116 


0117 


0118 


0119 


0560 


0368 


0369 


0370 


0371 


0372 


0373 


0374 0375 


0170 


0120 


0121 


0122 


0123 


0124 


0125 


0126 


0127 


0570 


0376 


0377 


0378 


0379 


0380 


0381 


0382 0383 


0200 


0128 


0129 


0130 


0131 


0132 


0133 


0134 


0135 


0600 


0384 


0385 


0386 


0387 


0388 


0389 


0390 0391 


0210 


0136 


0137 


0136 


0139 


0140 


0141 


0142 


0143 


0610 


0392 


0393 


0394 


0395 


0396 


0397 


0398 0399 


0220 


0144 


0145 


0146 


0147 


0148 


0149 


0150 


0151 


0620 


0400 


040 1 


0402 


0403 


0404 


0405 


0406 0407 


0230 


0152 


0153 


0154 


0155 


0156 


0157 


0158 


0159 


0630 


0408 


0409 


0410 


0411 


0412 


0413 


0414 0415 


0240 


0160 


0161 


0162 


0163 


0164 


0165 


0166 


0167 


0640 


0416 


0417 


04IB 


0419 


0420 


0421 


0422 0423 


0250 


CI 66 


0169 


0170 


0171 


0172 


0173 


0174 


0175 


0650 


0424 


0425 


0426 


0427 


0428 


0429 


0430 0431 


0260 


0176 


0177 


0178 


0179 


0180 


0181 


0182 


0183 


0660 


0432 


0433 


0434 


0435 


04 36 


04 37 


0438 0439 


0270 


0184 


0185 


0186 


0187 


0188 


0189 


0190 


0191 


0670 


0440 


044I 


0442 


0443 


0444 


0445 


0446 0447 


0300 


0192 


0193 


0194 


0195 


0196 


0197 


0198 


0199 


0700 


0448 


0449 


0450 


0451 


0452 


0453 


0454 0455 


0310 


0200 


0201 


0202 


0203 


0204 


0205 


0206 


0207 


0710 


0456 


0457 


0458 


0459 


0460 


0*61 


0462 0463 


0320 


0206 


0209 


0210 


0211 


0212 


0213 


0214 


0215 


0720 


0464 


0465 


0466 


0467 


0468 


0469 


0470 0471 


0330 


0216 


0217 


0218 


0219 


0220 


0221 


0222 


0223 


0730 


0472 


0473 


0474 


0475 


0476 


0477 


0478 0479 


0340 


0224 


0225 


0226 


0227 


0228 


0229 


0230 


0231 


0740 


0480 


0481 


0462 


0483 


0484 


0485 


0486 0487 


0350 


0232 


0233 


0234 


0235 


0236 


0237 


0238 


0239 


0750 


0488 


0469 


0490 


0491 


0492 


0493 


0494 0495 


0380 


0240 


0241 


0242 


0243 


0244 


0245 


0246 


0247 


0760 


0496 


0497 


0498 


0499 


0500 


0501 


0502 0503 


0370 


0248 


0249 


0250 


0251 


0252 


0253 


0254 


0255 


0770 


0504 


0505 


0506 


0507 


0506 


(1509 


0510 0511 







1 


2 


3 


4 


5 


6 


7 




i) 


I 


2 


3 


4 


5 


6 7 


1000 


0512 


0513 


0514 


0515 


0516 


0517 


0518 


0519 


1400 


0768 


0769 


0770 


0771 


0772 


0773 


0774 0775 


1010 


0520 


0521 


0522 


0521 


0524 


0525 


0526 


0527 


1410 


0776 


0777 


0778 


0779 


0780 


0781 


0762 0783 


1020 


0528 


0529 


0530 


0531 


0532 


0533 


0534 


0535 


1420 


0784 


0785 


0786 


0787 


0788 


0789 


0790 0791 


1030 


0536 


0537 


0536 


0539 


0540 


0541 


0542 


0543 


1430 


0792 


0793 


0794 


0795 


0796 


0797 


0796 0799 


1040 


0544 


0545 


0546 


0547 


0548 


0549 


0550 


0551 


1443 


0830 


080 1 


0802 


0803 


0804 


0805 


0806 0807 


1050 


0552 


0551 


0554 


0555 


0556 


0557 


0558 


0559 


1450 


0808 


0809 


08I0 


0811 


0812 


0813 


0614 0815 


1060 


0560 


U561 


0562 


0563 


0564 


0565 


0566 


0567 


1460 


0816 


0817 


08I8 


0819 


0820 


0821 


0822 0623 


1070 


0566 


0569 


0570 


0571 


0572 


0573 


0574 


0575 


1470 


0824 


0825 


0826 


0827 


0828 


0829 


0630 0831 


1100 


0576 


0577 


0576 


0579 


0580 


0581 


0582 


0583 


1500 


0832 


0833 


0834 


0835 


0836 


0837 


0838 0839 


1110 


0564 


0585 


0566 


0587 


0588 


0569 


0590 


0591 


1510 


0840 


064 1 


0842 


0843 


0844 


0845 


0846 0847 


1120 


0592 


0593 


0594 


0595 


0596 


0597 


0598 


0599 


1520 


0848 


0849 


0850 


0851 


0852 


0853 


0854 0855 


1130 


0600 


0601 


0602 


0603 


0604 


0605 


0606 


0607 


1530 


0656 


0657 


0858 


0859 


0860 


0861 


0862 0863 


1140 


0608 


0609 


0610 


0611 


0612 


0613 


0614 


0615 


1540 


0864 


0865 


0866 


0867 


0666 


0869 


0670 0671 


1150 


0616 


0617 


0618 


0619 


0620 


0621 


0622 


0623 


1550 


0872 


0873 


0874 


0875 


0876 


0877 


0878 0879 


1160 


0624 


0625 


0626 


0627 


0628 


0629 


0630 


0631 


1560 


0880 


088I 


0882 


0883 


0884 


0885 


0866 0867 


1170 


0632 


0633 


0634 


0635 


0636 


0637 


0638 


0639 


1570 


0888 


0889 


0890 


0891 


0892 


0691 


0694 0895 


1200 


0640 


0641 


0642 


0643 


0644 


0645 


0646 


0647 


1600 


0896 


0897 


0898 


0899 


0900 


0901 


0902 0903 


1210 


0648 


0649 


0650 


0651 


0652 


0651 


0654 


0655 


1610 


0904 


0905 


0906 


0907 


0908 


0909 


0910 0911 


1220 


0656 


0657 


0658 


0659 


0660 


0661 


0662 


0663 


1620 


0912 


091 3 


0914 


0915 


0916 


0917 


0918 0919 


1230 


0664 


0665 


0666 


0667 


0668 


0669 


0670 


0671 


1630 


0920 


092 1 


0922 


0923 


0924 


0925 


0926 0927 


1240 


0672 


067 3 


0674 


0675 


0676 


0677 


0678 


0679 


1640 


0928 


0929 


0930 


0931 


0932 


0933 


0934 0935 


1250 


0680 


0681 


0682 


0683 


0664 


0685 


0686 


0687 


1650 


0936 


0937 


0938 


0939 


0940 


0941 


0942 0943 


1260 


0688 


0689 


0690 


0691 


0692 


0693 


0694 


0695 


1660 


0944 


0945 


0946 


0947 


0948 


0949 


0950 0951 


1270 


0696 


0697 


0698 


0699 


0700 


0701 


0702 


0703 


1670 


0952 


0953 


0954 


0955 


0956 


0957 


0956 0959 


1300 


0704 


0705 


0706 


0707 


0708 


0709 


0710 


0711 


1700 


0960 


096 1 


0962 


0963 


0964 


0965 


0966 0967 


1310 


0712 


0718 


0714 


0715 


0716 


0717 


0718 


0719 


1710 


0968 


0969 


0970 


0971 


0972 


0972 


0974 0975 


1320 


0720 


0721 


0722 


0723 


0724 


0725 


0726 


0727 


1720 


0976 


0977 


0978 


0979 


0960 


0991 


0982 0983 


1330 


0728 


0729 


0730 


0731 


0732 


0733 


07 34 


0735 


1730 


098< 


0995 


0996 


0997 


0969 


0989 


0990 0991 


1340 


0736 


0737 


0736 


07 39 


0740 


0741 


0742 


0741 


1740 


0992 


0993 


0994 


0995 


0996 


0997 


0998 0999 


1350 


0744 


0745 


0746 


0747 


0748 


0748 


0750 


0751 


17J0 


1 000 


I001 


1 002 


1001 


1004 


1005 


1006 1007 


1360 


0752 


0753 


0754 


0755 


0756 


0757 


0758 


0759 


1760 


1 006 


1 009 


I0I0 


1011 


1012 


1011 


1014 1015 


1170 


0760 


0761 


0762 


0763 


0764 


0765 


0766 


0767 


1770 


I0I6 


1017 


1016 


1019 


1020 


1021 


1022 1023 



C-25 



January 1976 



MACRO Assembler, Instruction, and Character Code Summaries 










1 


2 


3 4 


5 


( 7 







1 


2 


3 


4 


5 


6 7 


2000 1024 


2000 


1024 


1025 


1026 


1027 103* 


1029 


1030 1011 


2400 


1280 


12(1 


12(2 


128) 


12(4 


12(5 


I2(( 12(7 


to 


to 


2010 


1032 


10)) 


1034 


1035 1036 


1037 


1038 1039 


2410 


1284 


12(9 


1290 


1291 


1292 


1293 


12(4 1295 


2777 


1535 


1020 


1040 


1041 


1042 


1043 1044 


1045 


1046 1047 


2420 


1298 


1297 


1298 


1299 


1300 


1301 


1302 1303 


(Octal) 


(Decimal) 


2030 


1046 


1049 


1050 


1051 I0S2 


1053 


1054 105S 


2430 


1304 


1)05 


1306 


1307 


1308 


1309 


1310 1311 




2040 


1056 


1057 


1058 


1059 1060 


1061 


1062 104) 


2440 


1312 


1313 


1314 


1315 


I3K 


1317 


I3K 1319 




2050 


1064 


1065 


1066 


10(7 10(6 


10(9 


1070 1071 


2450 


1320 


1)21 


1322 


1323 


1324 


1325 


1326 1327 




20«0 


1072 


1073 


1074 


1075 1076 


1077 


1078 1079 


24(0 


1326 


1)29 


1330 


1331 


1332 


1333 


1334 1335 


Octal Decimal 


2070 


10(0 


1081 


1082 


106) 1064 


10(5 


1066 10(7 


2470 


1336 


1)37 


1336 


1339 


1340 


1341 


1342 1343 


10000' 4096 
































20000- 8192 


2100 


1066 


10(9 


1090 


1091 1092 


1093 


1094 1095 


2500 


1344 


1345 


1346 


1347 


1348 


1349 


1350 1351 


30000 ■ 12288 


2110 


1096 


1097 


1098 


1099 1100 


1101 


1102 1103 


2510 


1352 


1353 


1354 


1355 


1356 


1357 


1356 1359 


40000- 16384 


2120 


1104 


1105 


1106 


1107 1109 


1109 


1110 llll 


2520 


1360 


13(1 


1332 


1363 


1364 


1365 


13(6 1367 


50000-20480 


21 JO 


1112 


III) 


1114 


HIS UK 


1117 


UK 1119 


2530 


1368 


13(9 


1370 


1371 


1372 


1373 


1374 1375 


60000 - 24576 


2140 


1120 


1121 


1122 


l!23 1124 


1125 


1126 1127 


2540 


1)78 


1377 


1376 


1379 


1380 


1381 


1382 1363 


70000 - 28672 


2150 


1121 


1129 


1130 


1131 11)2 


1133 


1134 1135 


2550 


13(4 


13(5 


1386 


1387 


1386 


1U89 


1390 1391 




2160 


11)6 


1137 


1138 


1139 1140 


1141 


1142 1143 


25(0 


1392 


1393 


1394 


1395 


1396 


1397 


1396 1)99 




2170 


1144 


1145 


1140 


1147 1148 


1149 


1150 1151 


2570 


1400 


1401 


1402 


1403 


1404 


1405 


1406 1407 




2200 


1152 


1153 


1154 


1155 1156 


1157 


1I5( 1159 


2(00 


1408 


1409 


1410 


1411 


1412 


1413 


1414 1415 




2210 


1160 


1161 


11(2 


11(3 11(4 


11(5 


1 166 11(7 


2(10 


1416 


1417 


1416 


1419 


1420 


1421 


1422 142) 




2220 


1168 


1169 


1170 


1171 1172 


1173 


1174 1175 


2(20 


1424 


1425 


1426 


1427 


1428 


1429 


14)0 14)1 




22)0 


1176 


1177 


1178 


1179 1180 


1161 


11(2 11(3 


2630 


1432 


1433 


1434 


1435 


1436 


1437 


14)8 14)9 




2240 


1164 


1165 


1186 


IIC 1188 


1189 


1190 1191 


2640 


1440 


1441 


1442 


1443 


1444 


1445 


1446 1447 




2250 


1192 


1193 


1194 


1195 1196 


1197 


1196 1199 


2650 


1448 


1449 


1450 


1451 


1452 


1453 


1454 1455 




22(0 


1200 


1201 


1202 


1203 1204 


1205 


1206 1207 


26(0 


1456 


1457 


1458 


1459 


14(0 


14(1 


14(2 14(3 




2270 


1206 


1209 


1210 


1211 1212 


1213 


1214 1215 


2(70 


14(4 


14(5 


1466 


14(7 


1468 


1469 


1470 1471 




2)00 


1216 


1217 


1218 


1219 1220 


1221 


1222 1223 


2700 


1472 


1473 


1474 


1475 


1476 


1477 


1476 1479 




2)10 


1224 


1225 


1226 


1227 1221 


1229 


1230 1231 


2710 


14(0 


14(1 


14(2 


14(3 


1484 


1485 


1488 1417 




2)20 


12)2 


12)3 


12)4 


1235 1236 


1237 


1238 1239 


2720 


I4(( 


1489 


1490 


1491 


1492 


1493 


1494 1495 




2)30 


1240 


1241 


1242 


1243 1244 


1245 


1246 1247 


2730 


1498 


1497 


1496 


1499 


1500 


1501 


1502 150) 




2340 


1246 


1249 


1250 


1251 1252 


1253 


1254 1255 


2740 


1504 


1505 


1506 


1507 


1508 


1509 


1510 1511 




2350 


1256 


1257 


1258 


1259 12(0 


12(1 


12(2 12(3 


2750 


1512 


1513 


1514 


1515 


I5K 


1517 


1518 1519 




2X0 


1264 


1265 


1266 


12(7 1268 


12(9 


1270 1271 


27(0 


1520 


1521 


1522 


1523 


1524 


1525 


1528 1527 




2)70 


1272 


1273 


1274 


1275 1276 


1277 


1276 1279 


2770 


152( 


1529 


1530 


1531 


1532 


1533 


15)4 1535 



























1 


2 


3 4 


5 


6 7 







1 


2 


3 


4 


5 


6 7 


3000 


1536 


3000 


15)6 


1537 


1538 


1539 1540 


1541 


1542 1543 


3400 


1792 


1793 


1794 


1795 


1796 


1797 


1796 1799 


to 


to 


3010 


1544 


1545 


1546 


1547 1541 


1549 


1550 1551 


3410 


1(00 


1(01 


1(02 


1(03 


1(04 


1(05 


1606 1(07 


3777 


2047 


3020 


1552 


1553 


1554 


1555 1556 


1557 


I55( 1559 


3420 


1(08 


1809 


1(10 


1811 


1(12 


1813 


1(14 1815 


(Octal) 


(Decimal) 


3030 


1560 


15(1 


1562 


1563 1564 


1565 


1566 15(7 


3430 


1(16 


1817 


l(l( 


1819 


1(20 


1(21 


1(22 182) 




3040 


1568 


1569 


1570 


1571 1572 


1573 


1574 1575 


3440 


1824 


1625 


1(26 


1827 


1(28 


1829 


18)0 1631 




3050 


1576 


1577 


1578 


1579 15(0 


15(1 


1582 15(3 


3450 


1832 


1833 


1834 


1635 


1836 
1844 


1637 


1838 16)9 




3060 


1584 


1585 


1586 


1587 1588 


1569 


1590 1591 


34(0 


1640 


1841 


1842 


■ 843 


1845 


1846 1847 




3070 


1592 


1593 


1594 


1595 1596 


1597 


1598 1599 


3470 


1848 


1849 


1850 


1851 


1652 


1853 


1654 1855 




3100 


1600 


1601 


1602 


1(03 1604 


1605 


1606 1607 


3500 


1856 


1857 


1658 


1859 


I860 


1861 


1662 1663 




3110 


1608 


1609 


1610 


1611 1612 


1613 


1614 1615 


3510 


1664 


IS6S 


1866 


1967 


1868 


1869 


1670 1871 




3120 


1616 


1617 


1618 


1619 1620 


1621 


1622 1(23 


3520 


1872 


1873 


1874 


1875 


1876 


1677 


1876 1879 




3130 


1624 


1(25 


1626 


1627 1(28 


1(29 


1(30 1(31 


3530 


I860 


1681 


1882 


1883 


1884 


1685 


1868 1887 




3140 


1632 


1633 


1(34 


1(35 1636 


1637 


1638 1639 


3540 


1888 


1889 


1(90 


1691 


1892 


1693 


1894 1895 




3150 


1640 


1641 


1(42 


1643 1644 


1645 


1646 1(47 


3550 


1696 


1897 


1898 


1699 


1900 


1901 


1902 1903 




3160 


1648 


1649 


1650 


1651 1(52 


1653 


I6j4 1655 


3560 


1904 


1905 


1906 


1907 


1908 


1909 


1910 1911 




3170 


1656 


1657 


1658 


1659 16(0 


1661 


16(2 16(3 


3570 


1912 


1913 


1914 


1915 


1916 


1917 


1916 1919 




3200 


1664 


1665 


1666 


1667 1(68 


16(9 


1670 1(71 


3(00 


1920 


1921 


1922 


1923 


1924 


1925 


1926 1927 




3210 


1672 


1673 


1674 


1(75 1676 


1677 


1678 1(79 


3610 


1929 


1929 


1930 


1931 


1932 


1933 


1934 1935 




3220 


1680 


1681 


1682 


1(83 16(4 


1665 


1(66 16(7 


3(20 


1936 


1937 


1938 


1939 


1940 


1941 


1942 1943 




3230 


1688 


1689 


1690 


1691 1692 


1(93 


1694 1695 


3630 


1944 


1945 


1946 


1947 


1948 


1949 


1950 1951 




3240 


1696 


1697 


1698 


1699 1700 


1701 


1702 1703 


3(40 


1952 


1953 


1954 


19S5 


1956 


1957 


1958 1959 




3250 


1704 


1705 


1706 


1707 (70S 


1709 


1710 1711 


3(50 


1960 


19(1 


1962 


1963 


1964 


1965 


19(6 1967 




3260 


1712 


1713 


1714 


1715 I7K 


1717 


1718 1719 


36(0 


1968 


1969 


1970 


1971 


1972 


1973 


1974 1975 




3270 


1720 


1721 


1722 


1723 1724 


1725 


1726 1727 


3670 


1976 


1977 


1978 


1979 


I960 


1991 


1962 1963 




3300 


1726 


1729 


1730 


1731 1732 


173) 


1734 1735 


3700 


1984 


19(5 


1986 


1987 


1986 


1989 


1990 1991 




3310 


1736 


1737 


1736 


1739 1740 


1741 


1742 1743 


3710 


1992 


1993 


1994 


1995 


1996 


1997 


I99( 1999 




3320 


1744 


1745 


1746 


1747 1746 


1749 


1750 1751 


3720 


2000 


2001 


2002 


2003 


2004 


2005 


2006 2007 




3330 


1752 


1753 


1754 


1755 1756 


1757 


1758 1759 


3730 


2006 


2009 


2010 


2011 


2012 


201) 


2014 201 5 




3340 


17(0 


1761 


1762 


1763 17(4 


1765 


1766 1767 


3740 


2016 


2017 


2018 


2019 


2020 


£021 


2022 2029 




3350 


17(6 


1769 


1770 


1771 1772 


1773 


1774 1775 


3750 


2024 


2025 


2026 


2027 


20*8 


2029 


2030 3031 




3360 


1776 


1777 


1778 


1779 17(0 


1781 


17(2 1793 


37(0 


2032 


2033 


2034 


2036 


2036 


2037 


2039 2039 






3370 1714 


1785 


1786 


•7(7 I78S 


17(9 


1799 1791 


3770 2040 


2041 


2042 


2041 


2044 


2045 


2046 2047 



January 1976 



C-2 6 



MACRO Assembler, Instruction, and Character Code Summaries 



4000 

to 
4777 
(Octal) 

Octal 

10000 

20000 

30000 

40000 

50000 

60000 

70000 



2048 

to 
2559 

(Decimal) 

Decimal 

- 4096 

- 8192 
• 12288 

■ 16384 
■20480 

■ 24576 
■28672 



5000 


2560 


to 


to 


5777 


3071 


(Octal) 


(Decimal) 





1 2 3 4 5 6 7 







1 


2 3 


4 


S ( T 


4000 


2048 2049 2050 2051 2052 2053 2054 2055 


4400 


2304 


2305 


2306 2307 


2306 


2309 2310 till 


4010 


2056 2057 2058 2059 2060 2061 20(2 2063 


4410 


2312 


2313 


2314 2315 


2316 


2317 2316 23! » 


4020 


2064 2065 2066 2067 2068 2069 2070 2071 


4420 


2320 


2321 


2322 2323 


2324 


2325 2326 2327 
2333 2334 1335 


4030 


2072 2073 2074 2075 2076 2077 2078 2079 


4430 


2328 


2329 


2330 2331 


2332 


4040 


2080 2081 2082 2083 2084 2085 2086 2087 


4440 


2336 


2337 


2338 2339 


2340 


2341 2342 134) 


4050 


2088 2089 2090 2091 2092 2093 2094 2095 


4450 


2344 


2345 


2346 2347 


2348 


2349 2330 2331 


4060 


2096 2097 2099 2099 2100 2101 2102 2103 


4460 


2352 


2353 


2354 2355 


2356 


2357 235( 2359 


4070 


2104 2105 2106 2107 2I0S 2109 2110 2111 


4470 


2360 


2361 


2362 2363 


2364 


2365 2366 2367 


4100 


2112 2113 2114 2115 2116 2117 2118 2119 


4500 


2368 


2369 


2370 2371 


2372 


2373 2374 2375 


4110 


2120 2121 2122 2123 2124 2125 2126 2127 


4510 


2376 


2377 


2378 2379 


2380 


2381 23(2 23(3 


4120 


2128 2129 2130 2131 2132 2133 2134 2135 


4520 


2384 


2385 


2386 2387 


2388 


2389 2390 2391 


4130 


2136 2137 2138 2139 2140 2141 2142 2143 


4530 


2392 


2393 


2394 2395 


2396 


2397 2398 2399 


4140 


2144 2145 2146 2147 2148 2149 2150 2151 


4540 


2400 


2401 


2402 2403 


2404 


2405 2406 2407 


4150 


2152 2153 2154 2155 2156 2157 2158 2159 


4550 


2408 


2409 


2410 2411 


2412 


2413 2414 2415 


4160 


2160 2161 2162 2163 2164 2165 2166 2167 


4560 


2416 


2417 


2419 2419 


2420 


2421 2422 2423 


4170 


2168 2169 2170 2171 2172 2173 2174 2175 


4570 


2424 


2425 


2426 2427 


2428 


2429 2430 2431 


4200 


2176 2177 2179 2179 2180 2181 2182 2183 


4600 


2432 


2433 


2434 2435 


2436 


2437 2438 2439 


4210 


2184 2185 2186 2187 2188 2189 2190 2191 


4610 


2440 


2441 


2442 2443 


2444 


2445 2446 2447 


4220 


2192 2193 2194 2195 2196 2197 2198 2199 


4620 


2448 


2449 


2450 2451 


2452 


2453 2454 2455 


4230 


2200 2201 2202 2203 2204 2205 2206 2207 


4630 


2456 


2457 


2458 2459 


2460 


2461 2462 2463 


4240 


2208 2209 2210 2211 2212 2213 2214 2215 


4640 


2464 


2465 


2466 246? 


2468 


2469 2470 2471 


4250 


2216 2217 2218 2219 2220 2221 2222 2223 


4650 


2472 


2473 


2474 2475 


2476 


2477 2478 2479 


4260 


2224 2225 2226 2227 2228 2229 2230 2231 


4660 


2480 


2481 


2482 2483 


2484 


2485 2486 2467 


4270 


2232 2233 2234 2235 2236 2237 2238 2239 


4670 


2468 


2489 


2490 2491 


2492 


2493 2494 2495 


4300 


2240 2241 2242 2243 2244 2245 2246 2247 


4700 


2496 


2497 


2499 2499 


2500 


2501 2502 2503 


4310 


2248 2749 2250 2251 2252 2253 2254 2255 


4710 


2504 


2505 


2506 2507 


2508 


2509 2510 2511 


4320 


2256 2257 2256 2259 2260 2261 2262 2263 


4720 


2512 


2513 


2514 2515 


2516 


2517 2518 2519 


4330 


2264 2265 2266 2267 2268 2269 2270 2271 


4730 


2520 


2521 


2522 2523 


2524 


2525 2626 2527 


4340 


2272 2273 2274 2275 2276 2277 2278 2279 


4740 


2528 


2529 


2530 2531 


2532 


2533 2534 253S 


4350 


2280 2281 2282 2283 2284 2285 2296 2287 


4750 


2536 


2537 


2538 2539 


2540 


2541 2542 2543 


4360 


2288 2289 2290 2291 2292 2293 2294 2295 


4760 


2544 


2545 


2546 2547 


2548 


2549 2550 2551 


4370 


2296 2297 2298 2299 2300 2301 2302 2303 


4770 


2552 


2553 


2554 2555 


2556 


2557 2558 2559 




12 3 4 5 6 7 







1 


2 3 


4 


5 6 7 


5000 


2560 2561 2562 2563 2564 2565 25.66 2567 


5400 


2616 


2817 


2818 2619 


2820 


2821 2622 2(23 


5010 


2566 2569 2370 2371 2572 2573 2574 2575 


5410 


2824 


2825 


2826 2827 


2828 


2829 2830 2(11 


5020 


2576 2577 2376 2379 2560 2581 2582 2563 


5420 


2832 


2833 


2834 2835 


2836 


2837 2838 2(3* 


5030 


25(4 25(5 25(6 25(7 25(8 25(9 2590 2591 


5430 


2840 


2841 


2842 2843 


2844 


2845 2846 2(47 


5040 


2592 2393 2594 25(5 2596 2597 2598 2599 


5440 


2848 


2849 


2850 2851 


2852 


2653 2(34 2851 


5050 


2600 2601 2602 2603 2604 2605 2606 2607 


5450 


2856 


2857 


2858 2859 


2860 


2661 2862 2(6) 


5060 


260( 2609 2610 2611 2612 2613 2614 2615 


5460 


2864 


2865 


2866 2867 


2868 


2869 2870 2(71 


5070 


2616 2617 2616 2(19 2620 2621 2622 2623 


5470 


2872 


2873 


2874 2875 


2876 


2877 2878 2(79 


5100 


2624 2625 2626 2627 2C28 2629 2630 2631 


5500 


2880 


2881 


2882 2883 


2884 


2885 2686 28(7 


5110 


2632 2633 2634 2635 2636 2637 2638 2639 


5510 


2888 


2889 


2890 2891 


2892 


2893 2(94 2(95 


5120 


2640 2641 2642 2643 2644 2645 2646 2647 


5520 


2896 


2897 


2898 2899 


2900 


2901 2902 2903 


5130 


2648 2649 2650 2651 2652 2653 2654 2655 


5530 


2904 


2905 


2906 2907 


2908 


2909 2910 2911 


5140 


2656 2657 2658 2659 2660 2661 2662 2663 


5540 


2912 


2913 


2914 2915 


2916 


2917 2918 2919 


5150 


2664 2665 2666 2667 2668 2669 2670 2671 


5550 


2920 


2921 


2922 2923 


2924 


2925 2926 2927 


51(0 


2672 2673 2674 2675 2676 2677 2678 2679 


5560 


2928 


2929 


2930 2931 


2932 


2933 2934 2933 


5170 


2680 2661 2682 2683 2684 2685 2686 2687 


5570 


2936 


2937 


2938 2939 


2940 


2941 2942 2943 


5200 


2688 2689 2690 2691 2692 2693 2694 2695 


5600 


2944 


2945 


2946 3947 


2948 


2949 2950 2951 


5210 


2696 2697 2698 2699 2700 2701 2702 2703 


5610 


2952 


2953 


2954 2955 


2956 


2957 2958 2959 


5220 


2704 2705 2706 2707 2708 2709 2710 2711 


5620 


2960 


2961 


2962 2963 


2964 


2965 2966 2967 


5230 


2712 2713 2714 2715 2716 2717 2718 2719 


5630 


2968 


29C9 


2970 297! 


2972 


2973 2914 2975 


5240 


2720 2721 2722 2723 2724 2725 2726 2727 


5640 


2976 


2977 


2978 2979 


2980 


2991 29(2 29(3 


5250 


2728 2729 2730 2731 2732 2733 2734 2733 


5650 


2984 


2985 


2986 2987 


2988 


2989 2990 2991 


5260 


2736 2737 2738 2739 2740 2741 2742 2743 


5660 


2992 


2993 


2994 2995 


2996 


2997 2996 2999 


5270 


2744 2745 2746 2747 2748 2749 2750 2751 


5670 


3000 


3001 


3002 3003 


3004 


3005 3006 3007 


5300 


2TS2 2753 2754 2755 2756 2757 2758 2759 


5700 


3008 


3009 


3010 3011 


3012 


3013 3014 3015 


5310 


2760 2761 2762 2763 2764 2765 2766 2767 


5710 


3016 


3017 


3018 3019 


3020 


3021 3022 3023 


5320 


2768 2769 2770 2771 2772 2773 2774 2775 


5720 


3024 


3025 


3026 3027 


3028 


3029 3030 3031 


5330 


2776 2777 2779 2779 2780 2761 2782 2783 


5730 


3032 


3033 


3034 3035 


3036 


3037 3038 3039 


5340 


2784 2785 2786 2787 2768 2789 2790 2791 


5740 


3040 


3041 


3042 3043 


3044 


3045 3046 3047 


5350 


2792 2793 2794 2793 2196 279T 2796 2799 


3750 


3048 


3049 


3050 3051 


3052 


3033 3034 3035 


53W 


2600 2601 2(02 2(03 2(04 2(03 2(06 2(07 


5760 


3056 


3057 


305( 3059 


3060 


3061 3062 3063 


5370 


2M» 2(09 2(10 2811 2(12 2(13 2(14 2(15 


5770 


3064 


3065 


3066 3067 


3068 


3069 3070 3071 
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MACRO Assembler, Instruction, and Character Code Summaries 



6000 

to 
6777 

(Octal) 



Octal 

10000 

20000 

30000 

40000 

50000 

60000 

70000 



3072 

to 
3583 

(Decima 



Decimal 
4096 
8192 
12288 
16384 
20480 
24576 
28672 



7000 

to 

7777 

(Octal) 



3584 

to 

4095 

(Decimal) 





1 


2 


1 4 


5 


6 


7 







1 


2 


3 


4 


5 


6 


7 


6000 


3072 3071 


3074 


1075 1076 


3077 


3078 


3079 


6400 


332( 


3329 


3330 


3331 


3332 


3333 


3334 


3335 


toio 


3060 3061 


30(2 


3063 30(4 


30(5 


3086 


30(7 


6410 


1116 


3337 


3336 


3339 


3340 


3341 


3342 


3343 


•0J0 


3066 3069 


3090 


3091 3092 


3093 


3094 


3095 


6420 


3344 


33*5 


3346 


3347 


3348 


3349 


3350 


3351 


6030 


3006 3007 


3096 


3099 3100 


3101 


3102 


3103 


64 30 


3332 


3353 


3354 


3355 


3356 


3357 


3358 


3359 


•04 


3104 3105 


3106 


3107 3108 


3109 


3110 


3111 


6440 


3360 


3361 


3362 


3363 


3364 


3365 


3366 


3367 


•050 


3112 3113 


3114 


3115 3116 


3117 


3118 


3119 


6450 


3366 


3369 


3370 


3371 


3372 


3373 


3374 


3375 


toeo 


3120 3121 


3122 


3123 3124 


3125 


3126 


3127 


6460 


3376 


3377 


3378 


3379 


3380 


3381 


3382 


3383 


(070 


3126 3129 


3130 


3131 3132 


3133 


3134 


3135 


6470 


3384 


3385 


3386 


3387 


3388 


3389 


3390 


3391 


6100 


3136 3137 


3138 


3139 3140 


3141 


3142 


3143 


6500 


3392 


3393 


3394 


3395 


3396 


3397 


3398 


3399 


6110 


3144 3145 


3146 


3147 3146 


3149 


3150 


3151 


6510 


3400 


3401 


3402 


3403 


3404 


3405 


3406 


3407 


6120 


3152 3153 


3154 


3155 3156 


3157 


3158 


3159 


6520 


3408 


3409 


3410 


3411 


3412 


3413 


3414 


3415 


6110 


3160 3161 


3162 


3163 3164 


3165 


3166 


3167 


6530 


3416 


3417 


3418 


3419 


3420 


3421 


3422 


3423 


6140 


3166 3169 


3170 


3171 3172 


3173 


3174 


3175 


6540 


3424 


3425 


3426 


3427 


3428 


3429 


3430 


3431 


6150 


3176 3177 


3178 


3179 3160 


3181 


3182 


3183 


6550 


3432 


3433 


3434 


3435 


3436 


3437 


3438 


34 39 


6160 


3184 3165 


31SS 


3187 3168 


3169 


3190 


3191 


6560 


3440 


3441 


3442 


3443 


3444 


3445 


3446 


3447 


6170 


3192 3193 


3194 


3195 3196 


3197 


3198 


3199 


6570 


3448 


3449 


3450 


3451 


3452 


3453 


3454 


3455 


6200 


3200 3201 


3202 


3203 3204 


3205 


3206 


3207 


6600 


3456 


3457 


3458 


3459 


3460 


3461 


3462 


3463 


6210 


3206 3209 


3210 


3211 3212 


3213 


3214 


3215 


6610 


3464 


3465 


3466 


3467 


3468 


3469 


3470 


3471 


6220 


3216 MIT 


3218 


3219 3220 


3221 


3222 


3223 


6620 


3472 


3473 


3474 


3475 


3476 


3477 


3478 


3479 


6230 


3224 3225 


3326 


3227 3228 


3229 


3230 


3231 


6630 


3480 


3481 


3482 


3483 


3484 


3485 


34 66 


3487 


6240 


3232 3233 


3234 


3235 3236 


3237 


3238 


3239 


6640 


3488 


3489 


3490 


3491 


3492 


3493 


3494 


3495 


6250 


3240 3241 


3242 


3243 3244 


3245 


3246 


3247 


6650 


3496 


3497 


3498 


3499 


3500 


3501 


3502 


3503 


6260 


3246 3249 


3250 


3251 3252 


3253 


3254 


3255 


6660 


3504 


3505 


3506 


3507 


3506 


3509 


3510 


3511 


6270 


3256 3257 


3258 


3259 3260 


3261 


3262 


3263 


6670 


3512 


3513 


3514 


3515 


3516 


3517 


3518 


3519 


6300 


3264 3265 


3266 


3267 3268 


3269 


3270 


3271 


6700 


3520 


3521 


3522 


3523 


3524 


3525 


3526 


3521 


6310 


3272 3273 


3274 


3275 3276 


3277 


3278 


3279 


6710 


3528 


3529 


3530 


3531 


3532 


3533 


3534 


3535 


6320 


3260 3281 


3262 


3283 3264 


3285 


3286 


3297 


6720 


3516 


3537 


3538 


3539 


3540 


3541 


3542 


3543 


6330 


3286 3289 


3290 


3291 3292 


3293 


3294 


3295 


6730 


3544 


3545 


3546 


3547 


3548 


3549 


3550 


3551 


6340 


3296 3297 


3296 


3299 3300 


3301 


3302 


3303 


6740 


3552 


3553 


3554 


3555 


3556 


3557 


3558 


3559 


6350 


3304 3305 


3306 


3307 3308 


3309 


3310 


3311 


6750 


3560 


3561 


3562 


3563 


3564 


3565 


3566 


3567 


6360 


3312 3313 


3314 


3315 3316 


3317 


3316 


3319 


6760 


3568 


3569 


3570 


3571 


3572 


3573 


3574 


3575 


6370 


3320 3321 


3322 


3323 3324 


3325 


3326 


3327 


6770 


3576 


3577 


3578 


3579 


3580 


3581 


3582 


3583 




1 


2 


3 4 


5 


6 


7 







1 


2 


3 


4 


5 


6 


7 


7000 


3564 3585 


3566 


3587 3588 


3599 


3590 


3591 


7400 


3840 


3841 


3842 


3843 


3844 


3845 


3846 


3847 


7010 


3592 3593 


3594 


3595 3596 


3597 


3598 


3599 


7410 


3848 


3849 


3850 


3851 


3852 


3853 


3854 


3855 


7020 


3600 3601 


3602 


1603 3604 


3605 


3606 


3607 


7420 


3856 


3857 


3858 


3859 


3860 


3861 


3862 


3863 


7030 


3608 3609 


3610 


3611 3612 


3613 


3614 


3615 


7430 


3864 


3865 


3866 


3867 


3668 


3869 


3870 


3871 


7040 


3616 3617 


3618 


3619 3620 


3621 


3622 


3623 


7440 


3872 


3B73 


3874 


3675 


3876 


3877 


3878 


3879 


7050 


3624 3625 


3626 


3627 3628 


3629 


3630 


3631 


7450 


3880 


3681 


3882 


3883 


3884 


3885 


3686 


3887 


7060 


3632 3633 


3634 


3635 3636 


3637 


3638 


3639 


7460 


3688 


3889 


3890 


3891 


3892 


3893 


3894 


3(95 


7070 


3640 3641 


3642 


3643 3644 


3645 


3646 


3647 


7470 


3896 


3897 


3898 


3899 


3900 


3901 


3902 


3903 


7100 


3648 3649 


3650 


3651 3652 


3653 


3654 


3655 


7500 


3904 


3905 


3906 


3907 


3908 


3909 


3910 


1911 


7110 


3656 3657 


3656 


3659 3660 


3661 


3662 


3663 


7510 


3912 


3913 


3914 


3915 


3916 


3917 


3918 


3919 


7120 


3664 3665 


3666 


3667 3668 


3669 


3670 


3671 


7520 


3920 


3921 


3922 


3923 


3924 


3925 


3926 


M2T 


7130 


3672 3673 


1674 


3675 3676 


3677 


3678 


3679 


7530 


3928 


3929 


3930 


3931 


3932 


3933 


3934 


3935 


7140 


36(0 3661 


36(2 


36(3 3664 


3665 


3666 


3687 


7540 


3936 


3937 


3938 


3939 


3940 


3941 


3942 


3943 


7130 


3661 3669 


3690 


3691 3692 


3693 


3694 


3695 


7550 


3944 


3945 


3946 


3947 


394( 


3949 


3950 


3951 


7160 


3696 3697 


3696 


1699 1700 


3T0I 


3702 


3703 


7560 


3952 


3953 


3954 


3955 


3956 


3957 


3958 


3959 


7170 


3704 3705 


1706 


1707 1706 


3709 


3710 


1711 


7570 


3960 


3964 


3*62 


39(1 


3964 


3965 


1966 


3967 


7200 


3712 1713 


1714 


1715 1716 


3717 


3718 


3719 


7600 


3968 


3969 


3970 


1971 


3972 


3973 


3974 


3975 


1110 


1720 3721 


1722 


1711 1714 


3725 


3726 


3727 


7610 


3976 


3977 


3978 


3979 


3980 


3991 


3982 


3983 


7220 


3726 3*29 


1710 


1711 1712 


1711 


3734 


3735 


7620 


3984 


3985 


3986 


3987 


3988 


3989 


3990 


3991 


7230 


3716 1717 


37 31 


3119 3740 


1741 


3742 


3743 


7630 


3992 


3991 


3994 


3995 


3996 


3997 


3998 


3999 


7240 


1744 1745 


3746 


1747 174! 


3749 


3750 


3751 


7640 


4000 


4001 


4002 


4003 


4004 


4005 


4006 


4007 


7230 


1751 1751 


3754 


3753 3756 


3757 


3756 


3759 


7650 


4008 


4009 


4010 


4011 


4012 


4013 


4014 


4015 


7260 


1760 1761 


3761 


1761 17(4 


3765 


3766 


3767 


7660 


4016 


4017 


4018 


4019 


4020 


4021 


1022 


4023 


7270 


176* 3769 


1770 


3771 377J 


1711 


3774 


3775 


7670 


4024 


4025 


4026 


4021 


4026 


4029 


4030 


4031 


7300 


3776 3777 


3778 


1779 37(0 


17(1 


37(2 


37(1 


7700 


4032 


4033 


4034 


4035 


4036 


4037 


4038 


4039 


7310 


37(4 37(5 


37(6 


17(7 1716 


37(9 


3790 


3191 


1710 


4040 


4041 


4042 


4043 


4044 


4045 


4046 


4047 


7310 


3792 1711 


3794 


1795 1796 


3797 


379( 


3799 


7720 


4048 


4049 


4050 


«5I 


4052 


4053 


4054 


4055 


7330 


2(00 3(01 


3802 


1103 3604 


1(05 


1(06 


1(01 


7730 


4056 


4057 


4058 


4059 


4060 


4061 


4062 


4063 


7340 


3(0( 3(09 


3810 


3111 3611 


3(13 


3(14 


1(13 


7140 


4064 


4065 


4066 


4061 


4068 


4069 


4070 


4071 


7333 


Kid 3617 


3618 


1(19 3810 


3(21 


3(22 


1(21 


1150 


4072 


4073 


4074 


4015 


4076 


4011 


4076 


4019 


7360 


1814 1(25 


3626 


MIT 302* 


3(29 


3(30 


Mil 


1160 


40(0 


4061 


4082 


4061 


4064 


4085 


4086 


4061 


7170 


3(31 3(33 


NH 
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APPENDIX D 
SYSTEM MACRO FILE 



The following is a listing of the system macro library, SYSMAC.SML. 
This file is stored on the system device, and used by MACRO when it 
expands the programmed requests discussed in Chapter 9. 



SYSMAC.SML— -SYSTEM MACRO LIBRARY 
FOR RTli V3C. 

DEC-11-0RSYA-E 

COPYRIGHT CO 1974,1973 

DIGITAL EQUIPMENT CORPORATION 
MAYNARO, MASSACHUSETTS 01754 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY 

ON A SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH 

THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, 

OR ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE MADE 

AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH SYSTEM AND TO 

ONE WHO AGREES TO THESE LICENSE TERMS. TITLE TO AND OWNERSHIP OF THE 

SOFTWARE SHALL AT ALL TIMES REMAIN IN DIGITAL. 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO 
CHANGE WITHOUT NOTICE AND SHOULD NOT BE CONSTRUED 
AS A COMMITMENT BY DIGITAL EQUIPMENT CORPORATION. 

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE 
OR RELIABILITY OF ITS SOFTWARE ON EQUIPMENT 
WHICH IS NOT SUPPLIED BY DIGITAL. 

EF,JO 
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SYSTEM MACRO FILE 

.MACRO ..Vt.. 

...VIM 

.ENOM 

.MACRO ,,V8.. 

.MCALL ...CM1,..,CM2,'...CM3....CM« 

...va«i 

.CNDM 



.MACRO 


...CM1 .AREA,. CODE, .CHAN 




.IF MB 


.AREA 






MOV 


.AREA,X0 




MOVB 


#. CODE, 1(0) 


.ENOC 






.IF nb 


.CHAN 
.IF ION <,CHAN»,«#0> 






CLRB 


C0) 




.IFF 






MOVB 


.CHAN, fa) 




.ENDC 




.ENDC 






.ENOM 






.MACRO 


...CM2 .ARG, .OFFSET, .INS 




.IIF NB 


«»ARG», MOV 


,ARG,.OFFSET(0) 


.IIF NB 


«.INS>, EM? 


*0375 


.ENOM 







.MACRO ...CMS .CHAN, .CODE 

MOV #.CODE**G400,X<* 
.IIF N8 «,CHAN», BI8B ,CHAN,X0 

EMT *0374 
.ENOM 

.MACRO ...CM4 . AREA, .CHAN, .BUFF, ,WCNT,.BLK,,CRTN,, CODE 

...CM1 <, AREA*, <.CODE»,«. CHAN* 

...CMg «.8LK»,a. 

...CM2 «.8UFF»,4. 

,..CM3 <.WCNT>,6. 

...CMS «.CRTN>,6.,X 

.ENOM 

.MACRO .CDFN . AREA, , ADD, ,NUM 
...CM1 <.AREA>,13.,#0 
,..CM2 <,AOD»,a. 
...CMS «.NUM»,4.,X 
.ENOM 

.MACRO .CHAIN 
• ■ • C M 3 , 8 * 

.ENOM 

, MACRO .CHCOPY .AREA, .CHAN, .OCHAN 

...CM1 «,AREA*,it.,«.CHAN> 

...CM8 <.OCHAN»,a,,X 
.ENOM 
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SYSTEM MACRO FILE 

.MACRO .CNTXSW .AREA, .ADD 

...CHI «.AREA>,27.,#G! 

...CM3 <.ADD>,a.,X 
.ENDM 

.MACRO ,CMKT .AREA, . ID. .TIME 
...CMi «,AREA»,i9,,#0 
„».CM3 <,ID»,g. 
.IF B .TIME 









CLR 


«.t0) 


.IFF 






MOV 


.TIME,4.C0) 


.ENDC 






EMT 


*0375 


.ENOM 










.MACRO 


.CLOSE 


,CHAN 






.IF OF 


...VI 




EMT 


' *O«lfe0+,CHA 


.IFF 










...CM3 


«„CHAN> 


i fe ■ 






.enoc 










.ENDM 











MOV 
MOV 


.0EV8PC-C6.) 
.OEFEXT, «■(«>.) 


CUR 


-Cfe.) 


MOV 


.CSTRINB,.(6.) 


EMT 


*03«4 



.MACRO .CSIGEN .DEVSPC. .OEFEXT, .C3TRING 

.IP B .C8TRING 

.IFF 

.ENOC 

.ENDM 

.MACRO .C3ISPC ,0UTSPC..DEFEXT,.C5TRING 

.IF B .CSTRING 

.IFF 

.ENOC 

.ENDM 

, MACRO .C3TAT .AREA, .CHAN, .ADD 

...CMI «,AREA*,83,,«.CHAN> 

...CMS «.ADD*,2..X 
.ENDM 

.MACRO .DATE 

MOV ##5«,X0 

mov *oa«.ac«n .x» 

.ENDM 



MOV 
MOV 


.OUT5PC,-Cfe.) 
. OEFEXT, •(&.) 


CLR 


-C6.) 


MOV 


.C3TRING,-(6.) 


EMT 


*03«5 
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SYSTEM MACRO FILE 

.MACRO .DELETE .AREA, .CHAN, .DEVBLK, .SPF 
.IF OF ...VI 

,I1F NB «.CHAN> MOV • ,CHAN,X0 

EMT *0<.AREA> 
.IFF 

...CM1 «„AREA»,0,«c.CHAN» 
...CM2 <.0EVBLK»,8. 
.IF 8 .SPF 

CUR «.(0) 
.IFF 

MOV ,SPF,<t.(0) 
.ENOC 

EMT *0375 
.ENOC 
.ENQM 

.MACRO .DEVICE .AREA. .ADD 

...CM1 «.AREA>,13.,#0 

...CMg «.AOD>,a.,X 

• ENQM 

.MACRO .DSTATUS .RETSPC, .DNAME 

.IIF NB <. DNAME*, MOV .DNAME, %0 

MOV ,RET8PC,-(fc.) 
EMT *03a2 
.ENOM 

.MACRO .ENTER .AREA, .CHAN, .DEVBLK, ,LEN, . SPF 
.IF OF ...VI 

MOV ,CHAN,X(3 
.IF B . DEVBLK 

CLR -Cfc.) 
.IFF 

MOV .DEVBLK, -Ci.) 
.ENDC 

EMT a O«40+.AREA> 
.IFF 

...CM1 <.AREA>,2.,<,CHAN»> 
...CM2 «.DEVBLK>,a. 
.IF NB ,LEN 

.IFF 

.ENDC 

.IF NB .SPF 

.IFF 

.ENOC 

,ENOC 

• ENOM 

.MACRO .EXIT 
.ENOM 



MOV 


.LEN,<t.(0} 


CLR 


«.C0) 


MOV 


.SPF.6.C0) 


CLR 


fc.CB) 


EMT 


*0175 



EMT *035P! 



January 1976 D-4 



SYSTEM MACRO FILE 

.MACRO .FETCH ,ADD,,0NAME 

.IIF NB <.0NAME», MOV ,DNAME,X(5 

MOV .AD0,»C6.) 
EMT *03«3 

.ENOM 

.MACRO .GTIM .AREA, .ADO 

...CMl <.AREA>,17.,#0 

...CMS «.AD0>,8.,X 
.ENQM 

.MACRO .6TJB .AREA,. ADD 
...CMl <.AREA>,lfe.,#0 
...CMS <.ADD»,3..X 
.ENOM 

.MACRO .HERR 
. . ,CM3 »5, 
.ENOM 

.MACRO .HRESET 

• ENOM 

.MACRO .INTEN .PRIO, .PIC 
.IF NB ,PIC 



EMT *0357 



.IFF 

.ENQC 
.ENOM 

.MACRO .LOCK 
.ENOM 



MOV M*Q54 1 •(«>.) 
JSR 5,,#Cfc.)+ 

J8R 5..#*054 

.WORD *C«.PRIO*32.>&?34. 

EMT *034fe 



.MACRO .LOOKUP .AREA. .CHAN, ,OEVBLK,.SPF 
.IF DF ...Vi 
,IIF NB «.CHAN>, MOV ,CHAN,%0 

EMT *O<20*.AREA> 

.IFF 

...CM1 <.AREA>,1,«.CHAN> 

...CMa «.DEVBLK>,8. 

.IF B .SPF 

CLR «.C0) 



• IFF 
.ENDC 

.ENOC 

.ENOM 



MOV .5PF.4.C0) 
EMT *0375 



.MACRO 


.MFP3 


.ADD 








MOV 


M*05«,-Ce>.) 






ADO 


#*03«»2,C6.) 






JSR 


7,#»(6,)+ 


.IIF NB 


«.AOO», 


MOVB 


tfc.)+».AOO 


.ENQM 
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SYSTEM MACRO FILE 

, MACRO ,MRKT , ARIA, .TIME, .CRTN. .ID 

...CMl «.AREA»,ie.,#0 

...CM2 «.TlME»,a. 

,.,.GM8 «,CRTN>,«. 

...CMS «.ID»,fe,,x 

.ENOM 

.MACRO .MTPS 
•Iir NB «.A0D», 
• X"IF NB «.AD0», 



,EN0M 



.ADD 




CLR 


■C6.) 


MOVB 


.AOD, (*..) 


MOV 


##*05#,-C6.) 


AOQ 


#*O360,(6.) 


JSR 


7.,M6.) + 



.MACRO .MWAIT 
...CMS ,9. 

.ENQM 

.MACRO .PRINT ,AOO 

.IIP NB «.AOD>, MOV ,ADD,%0 



.ENOM 



EMT w 0351 



„MACRQ .PROTECT .AREA,. ADO 
...CM! <.AREA>,a5,,#0 
...CM3 <.AD0»,2.,X 
.ENOM 

.MACRO .PURGE .CHAN 
...CMI <.CHAN>,3. 
.ENOM 

.MACRO .OSET .QADO,.QLEN 

,IIF NB «,QLEN>, MOVB ,QLEN,%0 

MOV ,QA00i»(6.i 
EMT *0353 

■ ENOM 

.MACRO .RCTRLO 

EMT *0355 
.ENOM 

.MACRO .RCVO .AREA, .BUFF, .WCNT 

...CM4 «. ARE A»,#0,«,BUFF»,«I.WCNT»,,# 1,22. 

.ENOM 

.MACRO .RCVOC .AREA, .BUFF, .WCNT, .CRTN 

...CM4 <.AREA>,#0,<,BUFF>,«.WCNT>,,<.CRTN»,a3. 

.ENOM 

.MACRO .RCVOW .AREA, .BUFF, ,WCNT 

...CM4 <.AREA>,#0,«.8UFF>,«i.WCNT>, ,#0,32. 

.ENOM 
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.MACRO .READ .AREA, .CHAN, .BUFF, .WCNT, ,BLK 

„IF DF ...VI 
,IIF NB <.WCNT>. MOV ,WCNT,X0 

MOV #1,-C6.) 
MOV ,BUFF,«C<i.) 
MQV .CHAN, -(6. 5 
EMT *O<g00+.AREA» 
IFF 

I..CM4 «.AREA»,<,CHAN»,«.8UFF»,«.WCNT»,<.BLK»>,#1,8. 

.ENOC 

„ENOM 

.MACRO .READC .AREA, .CHAN, .BUFF, .WCNT, .CRTN, ,8LK 

,IF OF ...VI 
,IIF NB «.CRTN>, MQV .CRTN,X«! 

MOV .WCNT, -(6.) 
MOV .BUFF, -(6.) 
MOV .CHAN, *C6,i 
EMT w O<a00+.AREA* 

.IFF 

...CM4 «, ARE A>,«.CHAN>,«. BUFF*, «.WCNT».,*,BLKi»,<«.CRTN»,e, 

• ENOC 

,ENOM 

.MACRO .READW .AREA, .CHAN, .BUFF, .WCNT, .BLK 

,IF OF ,,.Vi 
,IIF NB <.WCNT», MOV ,WCNT,X0 

CLR -C6.) 
MOV ,BUFF,»C6.) 
MOV .CHAN, -(6.) 
EMT *O«200*.AREA> 

,IFF 

,..CM4 <.AREA*,<.CHAN>,«.BUFF>,«,WCNT>,«,BLK*,#0,e. 

,ENDC 

.ENDM 

.MACRO .REGOEF 

R0"X0 

«i«Xl 

RZixa 

R3«X3 

R«»X4 
RS»X5 
SPfXfe 
IFC«X7 

.ENDM 

.MACRO .RELEASE .DEVBLK 

.IIF NB «.DEvBLK*, MOV ,OEVBLK,X0 

CLR -(6.) 



EMT 3! 0343 



.ENOM 
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.MACRO .RENAME .AREA, .CHAN, „DEVBLK 

•IF OF ...VI 

,IIF NB <,CHAN», MOV ,CHAN,%0 

EMT *O«100+.AREA» 
.IFF 

...CMi «.AREA>,«.,«.CHAN* 
...CM2 ^.DEVBLK^.Z.^X 

.ENOC 
,ENOM 

.MACRO .REOPEN .AREA. .CHAN, „CBLK 
.IF DF ...VI 

,IIF NB «.CHAN>, MOV .CHAN,X0 

EMT *O<t40*.AREA> 
.IFF 

...CMI <.AREA>,6.,<,CHAN> 
...CMg <.C8LK>,2.,X 

■ ENOC 
.ENOM 

.MACRO .SAVESTAT .AREA,. CHAN,. CBLK 
.IF OF ...VI 
,IIF NB <.CHAN>, MOV .CHAN,X0 

EMT *O«ia0*.AREA>. 
.IFF 

...CMI <.AREA>,5.#<.CHAN> 
...CM2 <.C8LK>,a.,X 
.ENOC 
.ENOM 

.MACRO .RSUM 
• ■ .CMS , 3, 
.ENOM 

.MACRO .SOAT .AREA, .BUFF, .WCNT 

...CM4 «.AREA>,#0,<.BUFF»,<.WCNT>,,#i,8l. 

.ENOM 

.MACRO .SDATC . AREA, .BUFF, .WCNT, .CRTN 

...CM4 <.AREA>,#0,<.BuFF>,<.WCNT»,,<.CRTN>,ai. 

.ENOM 

.MACRO .SDATW .ARE A , .BUFF, , WCNT 

...CM4 «.AREA>,#0,«,BUFF>,<.WCNT>,,Ht0,Sl. 

.ENOM 

.MACRO .9ERR 
...CM3 ,a. 

.ENOM 

.MACRO .SETTOP .ADD 

,IIF NB <.AOO>, MOV .AOO.X0 



EMT *035« 



.ENOM 

.MACRO .SFPA .AREA, .ADD 

...CMI «.AREA>,24,,#0 

...CMg «.ADO»,?,,X 

.ENOM 
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.MACRO .SPFUN .AREA, .CHAN, .CODE, .BUFF, ,WCNT, ,8LK, .CRTN 
...CMi <.AREA>»2«».i<.CHAN» 
...CM2 <„BlK*,g. 



...CMa 


«.BUFF>, 


4. 






• ««CMa 


<,WCNT>i 


fc. 






.IF NB 


.CODE 




MOVB 
MOVB 


#*O377.8.(0) 


,£NDC 










.IF S , 


CRTN 




CLR 


10. C0) 


.IFF 






MOV 


.CRTN, 10.(0) 


.ENOC 






EMT 


*Q375 


.ENOM 










.MACRO 


.SRESET 




EMT 


*o352 


.ENDM 










.MACRO 


• 3PN0 








...CM3 


il 








.ENOM 











.MACRO .SYNCH .AREA 
.IIF NB «.AREA», 



.ENOM 



MOV 
MOV 
JSR 



.AREA.%4 

P# w 054#%5 
5.,#*032«C5.5 



.MACRO .TUOCK 

. i .CM3 |7, 
.ENOM 

.MACRO .TRP3ET .AREA,, ADO 

...CMI <.AREA»,3.,#0 

...CM2 «.ADD»,2.,X 

.ENOM 



.MACRO .TTINR 








EMT 


*O3«0 


.ENDM 






.MACRO .TTVIN .CHAR 








EMT 


*O1«0 




BCS 


.-2 


.IIF NB «.CHAR>, 


MOVB 


%0, .CHAR 


.ENDM 






.MACRO .TTOUTR 








EMT 


*03ftl 


.ENOM 







.MACRO .TTYOUT .CHAR 
.IIF NB «,CHAR>, 



.ENDM 



MOVB 

EMT 

BCS 



.CHAR.X0 

*Q341 

.-2 
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.MACRO .TWAIT .AREA, .TIME 

...CM1 «. AREA>, 201,, #0 

...CM2 «,TIME» # 2.,X 
.ENOM 



EMT W 03«T 



EMT *O<a«0+.CHAN> 



.MACRO .UNLOCK 

.ENOM 

.MACRO .WAIT .CHAN 
.IP DF ...VI 

.IFF 

...CMS «.CHAN»,0 

.ENOC 

.ENOM 

.MACRO .WRITE .AREA, .CHAN,. BUFF, ,WCNT,.BUK 

.IF OF ...vi 
,IIF N8 «.WCNT>, MOV .WCNT,X0 

MOV #1,-(6.J 
MOV , BUFF, -(«,,! 
MOV .CHAN,«(fc.) 
EMT *O«g?0+.AREA» 

.IFF 

,,.CM<| «.AREA>,<.CHAN>,<.BUFF>,<.WCNT>',<.BLK»',#1,9. 

.ENOC 

.ENOM 

.MACRO .WRITW .AREA, .CHAN, .BUFF, .WCNT, ,BLK 

.IF DF ...VI 
.IIF NB <.WCNT>, MOV ,WCNT,X0 

CLR -Cfe.) 
MOV .BUFF, .(6.) 
MOV .CHAN, .(«,.) 

EMT *O<2?0+,AREA> 
.IFF 

...CM4 <.AREA>,<.CHAN>,«.8UFF>,«,WCNT>,<.BLK>,#0,9. 

.ENOC 

.ENOM 

.MACRO .WRITC .AREA, .CHAN,. BUFF, ,WCNT,.CRTN,.8LK 

.1^ OF ...VI 
•IIF NB <,CRTN>, MOV ,CRTN,Xa 

MOV ,WCNT,«(6.) 
MOV .BUFF, -(6.) 
MOV ,CHAN,-(fe,5 
EMT *O<230*.AREAi. 
IFF 

...CM<| <,AREA>,«.CHAN>,«.BUFF>,<.WCNT»,«.BLK>,<.CRTN».,9, 

.ENOC 

.ENOM 



January 1976 D-10 



APPENDIX E 
PROGRAMMED REQUEST SUMMARY 



E.l PARAMETERS 

The following parameters are used as arguments in various calls. (Any 
parameters used which are not mentioned here are particular to a 
request and the appropriate section in Chapter 9 should be consulted.) 

Parameter Description 

.addr an address, the meaning of which depends on 
the request being used 

.area a pointer to the EMT argument list 

.blk a block number specifying the relative block 

in a file where an I/O operation is to begin 

•buff a buffer address specifying a memory location 

into which or from which an I/O transfer is 
to be performed 

.chan a channel number in the range 0-377 (octal) 

.crtn the entry point of a completion routine 

.count file number for magtape/cassette operations 

•dblk the address of a four-word RAD50 descriptor 
of the file to be opened 

•num a number, the value of which depends on the 

request 

•went a word count specifying the number of words 
to be transferred to or from the buffer 
during an I/O operation 



E.2 REQUEST SUMMARY 

Refer to Appendix D (SYSMAC.SML) to 
expanded in assembly language code. 
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APPENDIX F 
BASIC/RT-11 LANGUAGE SUMMARY 



BASIC/RT-11 is a single-user conversational BASIC for use under the 
RT-11 system. While the BASIC language is one of the simplest 
computer languages to learn, it contains advanced techniques which the 
experienced programmer can use to perform more intricate manipulations 
or to express a problem more efficiently. 

BASIC/RT-11 interfaces with the RT-11 monitor to provide powerful 
sequential and random-access file capabilities and allows the user to 
save and retrieve programs from peripheral devices. BASIC/RT-11 has 
provision for alphanumeric character string I/O and string variables 
(12K or larger systems) and allows user-defined functions and assembly 
language subroutine calls from user BASIC programs. 

For details on using the BASIC language, and for instructions on 
running BASIC/RT-11, refer to the BASIC/RT-11 Language Reference 
Manual (DEC-11-LBACA-D-D) . A summary of the BASIC/RT-11 commands and ' 
error messages is included here for quick reference. 



F.l BASIC/RT-11 STATEMENTS 

The following summary of BASIC statements defines the general format 
for the statement and gives a brief explanation of its use. 

CALL "function name" [ (argument list) ] 

Used to call assembly language user 
functions from a BASIC program. 

CHAIN "file descriptor"[LINE number] 

Terminates execution of user program, 
loads and executes the specified program 
starting at the line number, if 
included. 

CLOSeU ) Closes the logical file specified. If 

U. #ivJ no file is specified, closes all files 

which are open. 

DATA data list Used in conjunction with READ to input 

data into an executing program. 
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DEF FNletter (argument) ^express ion 

Defines a user function to be used in 
the program (letter is any alphabetic 
letter) . 

DIM variable (n), variable (n,m) ,variable$(n) , variable? (n,m) 

Reserves space for lists and tables 
according to subscripts specified after 
variable name. 



END 



Placed at the physical end of the 
program to terminate program execution. 



FOR variable = expressionl TO expression2 STEP expression3 

Sets up a loop to be executed the 
specified number of times. 



GOSUB line number 
GO TO line number 



Used to transfer control to a specified 
line of a subroutine. 

Used to unconditionally transfer control 
to other than the next sequential line 
in the program. 



IF expression rel.op. expression/ THEN K line number 

1GO TO] 



i 



IF END #n/THEN 
^GO TO 

INPUT list 



■)" 



line number 



Used to conditionally transfer control 
to the specified line of the program. 



Used to test for end file on sequential 
input file #n. 

Used to input data from the terminal 
keyboard or papertape reader. 



INPUT lexpression: list 
[let] variable=expression 
[LET] VFn(i)=expression 

NEXT variable 



Inputs from a sequential file 
particular device. 



or 



Used to assign a value to the specified 
variable. 

Used to set the value of a virtual 
memory file element. 

Placed at the end of a FOR loop to 
return control to the FOR statement. 



OPEN file 



>FOR f INPUT Y][(b)] AS FILE #n [DOUBLE BUF] 



\0UTPUTjJ 



OPEN file 



FOR /"INPUT "\ 
lOUTPUTJ. 



Opens a sequential file for input or 
output as specified. File may be of the 
form "dev:filnam.ext" or a scalar string 
variable. The number of blocks may be 
specified by b. 

[(b)] AS FILE VFnx (dimension) =string length 

Opens a virtual memory file for input or 
output. x represents the type of file: 
floating point (blank) , integer (%) , or 
character strings ($) . File may be of 
the form "devifil.ext" or a scalar 
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OVERLAY "file descriptor" 



PRINT list 



PRINT "text" 



string variable. The number of blocks 
may be specified by b. 

Used to overlay or merge the program 
currently in memory with a specified 
file, and continue execution. 

Used to output data to the terminal. 
The list can contain expressions or text 
strings. 

Used to print a message or a string of 
characters. 



PRINT #expression: expression list 

Outputs to a particular output device, 
as specified in an OPEN statement. 



PRINT TAB(x) ; 
RANDOMIZE 

READ variable list 

REM comment 
RESTORE 
RESTORE #n 



RETURN 



STOP 



Used to space to the specified column. 

Causes the random number generator to 
calculate different random numbers every 
time the program is run. 

Used to assign the values listed in a 
DATA statement to the specified 
variables. 

Used to insert explanatory comments into 
a BASIC program. 

Used to reset data block pointer so the 
same data can be used again. 

Rewinds the input sequential file #n to 
the beginning. 

Used to return program control to the 
statement following the last GOSUB 
statement. 

Used at the logical end of the program 
to terminate execution. 



F.2 BASIC/RT-11 COMMANDS 

The following key commands halt program execution, erase characters or 
delete lines. 



Key 
ALTMODE 

CTRL C 



Explanation 

Deletes the entire current line. Echoes DELETED 
message (same as CTRL U) . On some terminals the 
ESC key must be used. 

Interrupts execution of a command or program and 
returns control to the RT-11 monitor. BASIC may 
be restarted without loss of the current program 
by using the monitor REENTER command. 
F-3 
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CTRL O Stops output to the terminal and returns BASIC to 
the READY message when program or command 
execution is completed. 

CTRL U Deletes the entire current line. Echoes DELETED 
message (same as ALTMODE) . 

+■ (SHIFT 0) Deletes the last character typed and 

echoes a backarrow (same as RUBOUT) «. On VT05 or 
LA30 use the underscore (_) key. 

RUBOUT Deletes the last character typed and echoes a 
backarrow (same as «-) . 

The following commands list, punch, erase, execute and save the 
program currently in memory. 

Command Explanation 

CLEAR Sets the array and string buffers to nulls 

and zeroes. 

LIST Prints the user program currently in memory 

on the terminal. 

LIST line number 

LIST -line number 

LIST line number- [END] 

LIST line number-line number 

Types out the specified program line(s) on 

the terminal. 

LISTNH line number 

LISTNH -line number 

LISTNH line number- [END] 

LISTNH line number-line number 

Lists the lines associated with the specified 
numbers but does not print a header line. 

NEW "filnam" Does a SCRatch and sets the current program 

name to the one specified. 

OLD "file" Does a SCRatch and inputs the program from 

the specified file. 

RENAME "filnam" Changes the current program name to the one 

specified. 

REPLACE "dev: filnam. ext" 

Replaces the specified file with the current 
program. 

RUN Executes the program in memory. 

RUNNH Executes the program in memory but does not 

print a header line. 

SAVE "dev: filnam. ext" 

Outputs the program in memory as the 
specified file. 
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SCRatch Erases the entire storage area. 

F.3 BASIC/RT-11 FUNCTIONS 

The following functions perform standard mathematical operations in 
BASIC. 

Name Explanation 

ABS(x) Returns the absolute value of x. 

ATN(x) Returns the arctangent of x as an angle in radians 
in the range + or - pi/2. 

BIN(x$) Computes the integer value of a string of blanks 
(ignored), l's and O's. 

COS(x) Returns the cosine of x radians. 

EXP(x) Returns the value of etx where e=2. 71828. 

INT(x) Returns the greatest integer less than or equal to 
x. 

LOG(x) Returns the natural logarithm of x. 

OCT(x$) Computes an integer value from a string of blanks 
(ignored) and digits from to 7. 

RND(x) Returns a random number between and 1. 

SGN(x) Returns a value indicating the sign of x. 

SIN(x) Returns the sine of x radians. 

SQR(x) Returns the square root of x. 

TAB(x) Causes the terminal type head to tab to column 
number x. 

The string functions are: 

ASC(x$) Returns as a decimal number the seven-bit internal 
code for the one-character string (x$) . 

CHR$(x) Generates a one-character string having the ASCII 
value of x. 

DAT $ Returns the current date in the format 07-MAY-73. 

LEN(x$) Returns the number of characters in the string 
(x$). 

POS(x$,y$,z) Searches for and returns the position of the first 
occurrence of y$ in x$ starting with the zth 
position. 
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SEG$(x$,y,z) Returns the string of characters in positions y 
through z in x$. 

STR$(x) Returns the string which represents the numeric 
value of x. 

TRM$(x$) Returns x$ without trailing blanks. 

VAL(x$) Returns the number represented by the string (x$). 



F.4 BASIC/RT-11 ERROR MESSAGES 

The information that formerly appeared in Section F.4 has now been 
incorporated into the RT-11 System Message Manual , DEC-11-0RMEA-A-D. 
BASIC/RT-11 error messages are also found in the BASIC/RT-11 Language 
Reference Manual, DEC-11-LBACA-D-D. 
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APPENDIX G 
FORTRAN LANGUAGE SUMMARY 



FORTRAN IV is a problem-solving language designed to allow scientists 
and engineers to express mathematical operations in a familiar format. 

A FORTRAN source program is composed of a series of statements. 
Statements are usually made up of one- or two-word commands, which, 
when used in conjunction with data variables and constants, can be 
used to control procrram execution, assign values to variables and read 
and write data. The FORTRAN library contains routines to simplify 
mathematical functions such as computing sines, cosines, square roots, 
etc. The source program is translated by the FORTRAN compiler into a 
machine language program which, when linked with the FORTRAN object 
time routines, can be executed by the computer. 

This appendix describes first how to run a FORTRAN program as a 
foreground job, and then summarizes briefly the RT-11 FORTRAN IV 
language, statements, and error messages. For details, refer to the 

PDP-11 FORTRAN Language Reference M anual and the RT-11/RSTS/E I 
FORTRAN IV User's Guide . ' ~ \ 

The FORTRAN programmer may also want to read Appendix for details 
concerning the FORTRAN System Subroutine Library. SYSLIB allows the 
programmer to easily call and use the programmed requests described in 
Chapter 9. A summary of the SYSLIB library calls is in Table 0-1 



G.l RUNNING A FORTRAN PROGRAM IN THE FOREGROUND 

Since the FORTRAN Object Time System needs work areas to perform some 
of its functions, the FRUN/N!x monitor command must be used to 
allocate the needed space when running a FORTRAN program as a 
foreground job. The following formula can be used to calculate the 

decimal number (x) which must be designated to the /N option: 

x = 1/2 [378 + (29*N) + (R-136) + A*512) ] 
where : 

N ■ the value of the /N FORTRAN compiler switch option (the 
compiler defaults this to 6 ) . 

R ■ the value of the /R FORTRAN compiler switch option (the 
compiler defaults this to 210 octal, 136 decimal). 
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A = the number of I/O buffers in simultaneous use during 

execution. (Console terminal I/O does not require any 

buffers. Each open logical unit typically requires one 
buffer . ) 

For example, to calculate x for a program (FILENA.REL) which uses only 
terminal I/O and allows the compiler to assign the standard defaults, 
set the formula as follows (all values are decimal) : 

x = 1/2 [378 + (29*6) + (136-136) + (0*512) ] 

276 decimal words are required. The FORTRAN program is executed using 
the FRUN command as shown: 

.FRUN FILENA.REL/NI276 <CR> 

NOTE 

An exception can occur if the size of 
the linked FORTRAN program is less than 
the size of the USR (2K) and the USR is 
to be swapped. In this case, additional 
space must be allocated to allow the USR 
to successfully swap over the linked 
FORTRAN program. The additional space 
needed may be calculated by subtracting 
the size of the linked FORTRAN program 
from 10000 octal bytes (the size of the 
USR) and adding this result to the value 
of x previously calculated. 



G.2 FORTRAN CHARACTER SET 

The characters that may appear in a FORTRAN statement are restricted 
to those listed below. 

1. The letters A through Z 

2. The numerals through 9 

3. The following "special" characters: 

Character Name 

Space or Blank 

= Equals 

+ Plus 

Minus 

* Asterisk 

/ Slash 

( Left Parenthesis 
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) Right Parenthesis 

, Comma 

Decimal Point 

, Apostrophe 

" Double Quote 

$ Dollar Sign 

Other printable characters may appear in a FORTRAN statement only as 
part of a Hollerith constant or alphanumeric literal. Any printable 
character may appear in a comment. 



G.3 EXPRESSION OPERATORS 

Each group of operators is shown in order of descending precedence 
during execution. 



Type 

Arithmetic 

** 
*,/ 



+.- 



Operator 



exponentiation 
multiplication , 
division, 

addition, subtraction 
unary minus 



Operates Upon 



numeric constants, 
variables and 
expressions 



Relational 



.GT. 


greater than 


.GE. 


greater than or 




equal to 


• LT. 


less than 


.LE. 


less than or 




equal to 


.EQ. 


equal to 


.NE. 


not equal to 


Logical 




.NOT. 


.NOT. A is true if and 




only if A is false. 




and is false if A is 




true. 



.AND. 



.OR. 



variables , 
constants , 
and arithmetic 
expressions (all 
relational operators 
have equal priority) 



logical variables, 
logical constants, 
integer variables 
and constants, logical 
integers and expressions 



A.AND.B is true if 
and only if A and B 
are both true and is 
false if either A or 
B is false. 

A.OR.B is true if and 
only if either A or 
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B or both A and B 
are true, and false 
if both A and B 
are false. 

,EQV. A.EQV.B is true if and 
only if A and B 
are both true or if A 
and B are both false. 

,XOR. A.XOR.B is true if and only 
if A is true and B is 
false or if B is true 
and A is false. 



G.4 SUMMARY OF FORTRAN STATEMENTS 

The following is a summary of statements available in the PDP-11 
FORTRAN IV language, including the general format for the statement 
and its effect. 



Statement Formats 



Effect 



Arithmetic/Logical Assignment 
variable=expression 



The value of the arithmetic or 
logical expression is assigned 
to the variable. 



Arithmetic Statement Functions 

name ( varl , var2 , . . . ) =expression 



Creates a user-defined 
function having the variables 
(var) as dummy arguments,, 
When referenced, the 
expression is evaluated using 
the actual arguments in the 
function call. 



ACCEPT 

ACCEPT f,list 

ASSIGN 

ASSIGN n TO ivar 



Reads input from logical unit 
5 (TT: is default); f is the 
format statement label and 
list is an optional data list. 



Assigns the statement number n 
to the integer variable ivar. 
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FILEX 
where: 

dev: 

DTn: 
A 

/S 
/T 
Examples : 



= disk or DECtape (DK is assumed if no device is 
specified) . 

= DECsystem-10 DECtape. 

■ the switch from Table J-l which indicates a 
listing is desired (/F may be substituted if a 
"fast listing" is preferred) . 

= the switch from Table J-l which designates a 
DOS /BATCH or RSTS-11 block-replaceable device. 

« the switch from Table J-l which designates a 

DECsystem-10 block-replaceable device. 



*RK1:/L/S 
BRDB . SVS 



MONLIB 
DU11 
VERIFV 
CILUS 



CIL 
PAL 
LDR 
LDfl 



1 22-JUL-74 

175C 22-JUL-74 

45 24-JUL-74 

67C 22-JUL-74 

39 22-JUL-74 



This command lists the complete disk directory of the device RK1. the 
letter "C following the file size on a DOS/BATCH or RSTS directory 
listing indicates the file is a contiguous file. 



+ DT1:*. PFlL/L/S 

This command lists all files with the extension .PAL which are Ion 
drive 1. 

*DT1 : *. */F/T 

All files on DECsystem-10 formatted DECtape 1, regardless of filename 
or extension, are listed; a fast directory is requested (/F) in which 
only filenames are printed. 



J. 2. 5 Deleting Files from DOS /BATCH (RSTS) DECtapes 

FILEX may be used to delete files from, and zero directories 0f, 

DOS/BATCH and RSTS formatted DECtapes. The format of these command 
lines is: 



or 



*dev: f ilnam.ext/S/D 

*dev:/S/Z 

dev:/Z ARE YOU SURE? 



to delete a file 
to zero a directory 



where : 

devs = DOS /BATCH or RSTS DECtape. 

filnam.ext - a valid DOS /BATCH (RSTS) 
extension. 



filename ajnd 
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FILEX 

/S 

/D 
/Z 
Examples : 



= the switch from Table J-l which designates that 

the device is a DOS/BATCH (RSTS) block-replaceable 
device. 

■ the switch from Table J-l which designates that a 
file is to be deleted. 

■ the switch from Table J-l which designates that a 
directory is to be zeroed. 



*DT6 :*. PRL.'C-.-'S 



All files on DECtape with the extension .PAL are deleted. 

*DT2 :TflBLE. 0BJ/D,'S 

The file TABLE. OBJ is deleted from the DECtape on unit 2. 

*DT0:.-'Zr J 5 

DT8:.'Z ARE VOU SURE ?V 

The DECtape on drive is initialized in DOS /BATCH (RSTS) 
that it contains no files. 



format so 



J. 3 FILEX ERROR MESSAGES 

Following is a list of error messages that may occur under FILEX: 



Message 



Meaning 



?filnam.ext ALREADY EXISTS? 

An attempt was made to create the named file 
(filnam.ext) on a DOS DECtape when a file 
already existed under the name specified. 
Use /D to delete the file, and retry the 
transfer. 



?BAD PPN? 



?COR OVR? 



?DEV FULL? 



?DIR ERR? 



The DOS/BATCH user identification code was 
not in the form [nnn,nnn] , where each nnn is 
an octal number less than or equal to 
377 (octal). 

There was insufficient main storage for 
buffers and input list expansion. Try 
copying files one at a time, without using 
the "wild-card" (*.*) construction on input. 

There was no room in the directory for the 

filename or there was no room on the output 

device for the file (in which case the 

filename is not placed in the output device 
directory) . 

An error occurred while reading or looking up 
the directory of the input device, or the 
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input device does not have 
structure. 



the proper file 



PFEATURE NOT IMP? 
?FG ACTIVE? 

?FIL NAM? 
?FIL NOT FND? 

?ILL CMD? 



?ILL DEV? 



?ILL SWT? 

?IN ERR? 
?NO UFD? 

?OUT ERR? 
?SWT ERR? 



An operation was attempted which FILEX cannot 
perform (e.g., zeroing an RT-11 device). 

An attempt was made to use /T when a 

foreground job was active. The transfer is 

not allowed until the foreground job is 
terminated and unloaded via UNLOAD FG. 

The output filename was invalid or null. 

The input file was not found, or the 
"wild-card" (*.*) construction matched none 
of the existing files. 

The length of the command line exceeded 72 
characters; the command line was not in 
proper CSI format; the UIC exceeded the 
allowed number of characters or [ was used 
without ]; a "wild-card" (*.*) construction 
was used on a sequential-access device; no | 
output or no input file was specified for a 
copy operation, or more than one filename 
construction (dev:filnam.ext) was specified 
on either side of the = (<) sign. 

The device handler was not found, an invalid 
or illegal device name was used, or one of i 
the following was attempted : 

RK or DT was not used for DOS/BATCH 

(RSTS) input in a copy operation; 

DT was not used for DOS/BATCH (RSTS) 
output in a zero or delete operation; 

DT was not used for DOS/BATCH (RSTS) 
output in a copy operation; 

DT was not used for DECsystem-10 input 
in any operation. 

An illegal switch was used in a command line 
(e.g., a switch not listed in Table J-l) . 

A device error occurred on input. 

The specified UFD was not found on the DOS 
input disk. 

A device error occurred on output. 

An attempt was made to use more than one /S 
or /T switch in a command line (only one is 
allowed) ; an attempt was made to use more 
than one transfer mode switch (/I, /P, /A) or 
more than one operation switch (/D, /L, /F, 
/Z) in a command line (only one of each is 
allowed) . 
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PRINT 



PRINT f,list 



READ 
Formatted 



Writes output on logical unit 
6 (LP: is default) ; f is the 
format statement label and 
list is an optional data list. 



READ(u,f) 
READ (u,f) list 
READ f,list 



Reads at least one logical 
record from device u according 
to format specification f and 
assigns values to the 
variables in the list. 
Logical unit number 1 is used 
as default in the third form 
above. 



Unformatted 



READ(u) 
READ(u) list 



Reads one logical record from 
device u, assigning values to 
the variables in the list. 



Direct Access 



READ (u'r) list 



Reads from logical unit number 
u, record number r, and 
assigns values to the 
variables in the list. 



Transfer of Control on Error 



END=n 
ERR-m 
END=n,ERR=m 



Optional elements in the READ 
statement list (e.g., 
READ(u,f, END=n, ERR=m) 
allowing control transfer on 
error conditions. If an 
end-of-file condition is 
detected and END=n is 
specified, execution continues 
at statement n. If a hardware 
I/O error occurs and ERR=m is 
specified, execution continues 
at statement m. 
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RETURN 

RETURN 

REWIND 



Returns control to the calling 
program from the current 
subprogram. 



REWIND u 



Logical unit number u is 
repositioned to the beginning 
of the currently opened file. 



STOP 



STOP 

STOP display 



SUBROUTINE 



SUBROUTINE name 

SUBROUTINE name ( var 1, var 2,. . .) 



Terminates program execution 
and prints the octal constant, 
Hollerith constant, or 
alphanumeric literal display, 
if one is specified. 



Begins a SUBROUTINE 
subprogram, indicating the 
program name and any dummy 
variable names (var) . 



TYPE 



TYPE f,list 



Type Declarations 

type var 1 , var2 , . . . , vark 



Writes output on logical unit 
7 (TT: is default); f is the 
format statement label and 
list is an optional data list. 



The variable names, (var) , are 
assigned the specified data 
type in the program unit, 
type is one of: 

INTEGER (*2,*4) 
REAL(*4,*8) 
DOUBLE PRECISION 
COMPLEX (* 8) 
LOGICAL (*4,*1) 

The optional * indicates that 
an explicit length is to be 
set for the variable; the 
number that follows is the 
length in bytes. The length 
must be one of the permitted 
values above. 



G-10 



FORTRAN Language Summary 

WRITE 

Formatted 

WRITE (u,f) 
WRITE (u,f) list 



Causes one or more logical 
records containing the values 
of the variables in the list 
to be written onto device u 
according to the format 
specification f. 



Unformatted 



WRITE (u) 
WRITE (u)list 



Direct Access 



WRITE (u'r) list 



Transfer of Control on Error 

END=n 
ERR=m 
END=»n,ERR=m 



Causes one logical record 
containing the values of the 
variables in the list to be 
written onto device u. 



Causes one logical record 
containing the values of the 
variables in the list to be 
written onto record r of the 
logical unit number u. 



Optional elements in the WRITE 
statement list (e.g., WRITE 
u,f, END=n, ERR=m) allowing 
control transfer on error 
conditions, if an end-of-file 
condition is detected and 
END=n is specified, execution 
continues at statement n. If a 
hardware I/O error occurs and 
ERR=m is specified, execution 
continues at statement m. 



G.5 COMPILER ERROR DIAGNOSTICS 

The information that formerly appeared in Sections G.5 and G.6 has 
been incorporated into the RT-11 System Message Manual , DEC-11-0RMEA- 
A-D. RT-11 FORTRAN error messages are also found in the RT- 11/RSTS/E 
FORTRAN IV User's Guide , DEC-11-LRRUA-A-D. 
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APPENDIX H 
F/B PROGRAMMING AND DEVICE HANDLERS 



H.l F/B PROGRAMMING IN RT-11, VERSION 2 

Certain programming conventions must be observed in RT-11, Version 2, 
which were not required in Version 1. These conventions are necessary 
to permit interrupt routines to function properly while running two 
jobs in the F/B environment. All Version 2 device handlers follow 
these conventions; the user is urged to consult the listings of the 
example handlers (Section H.3) as they illustrate some of the 
techniques discussed. 

NOTE 

Device handlers distributed with RT-11, 
Version 1, will not work properly with 
Version 2. Also, any user-written device 
handlers should be re-written to comply 
with the Version 2 conditions. 
Instructions for interfacing new 
handlers to RT-11 are provided in the 

RT-11 Software Support Manual . 

( DEC- 11-0RPGA-B-5K Section HT2 
describes Version 2 device handlers. 

The procedures described in this appendix are necessary and must be 
followed to prevent system failures when jobs are running under RT-11. 
If at any time a program which services its own interrupts (and does 
not follow the guidelines described here) is run with another job, the 
system may malfunction. Therefore, it is required that all programs 
follow the procedures that are indicated here. 



H.l.l Interrupt Priorities 

The status word for each interrupt vector should be set such that when 
an interrupt occurs, the processor takes it at level 7. Thus, a device 
which has its vectors at 70 and 72 has location 70 set to its service 
routine; location 72 contains 340. The 340 causes the service routine 
to be entered with the processor set to inhibit any device interrupts. 
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H.1.2 Interrupt Service Routine 

If the conventions outlined in Section H.l.l are followed, when an 
interrupt occurs, the processor priority will be 7. The first task of 
the interrupt service routine is to lower the processor priority to 
the correct value. This can be done using the .INTEN macro call. The 
call is : 

.INTEN .priority 
or 

. INTEN . priority , . pic 

The .INTEN call is explained in Chapter 9, Programmed Requests. On 
return from the .INTEN call, the processor priority is set properly; 
registers 4 and 5 have been saved and can be used without the 
necessity of saving them again. 

For example, a user device interrupts at processor priority 5: 

DEVPRI=5 

DEVTNTs .INTEN DEVPRI ;NOTE, NOT #DEVPRI 



RTS PC 

If the contents of the processor status word, loaded from the inter- 
rupt vector, is of significance to the interrupt service routine (e.g., 
the condition bits) , the PS should be moved to a memory location (not 
the stack) before issuing the .INTEN. A device handler's interrupt 
service routine uses the monitor stack and should avoid excessive use 
of stack space. 

H.1.3 Return from Interrupt Service 

When an interrupt has been serviced, instead of issuing an RTI to 
return from the interrupt, the routine must exit with an RTS PC. This 
RTS PC returns control to the monitor, which then restores registers 4 
and 5, and executes the RTI. 

When a device handler has completed a transfer and is ready to return 
to the monitor via the internal monitor completion address, R4 must 
be pointing to the fifth word of the handler. It is no longer 
necessary to have RO and R3 on the stack, as it was in Version 1. The 
user is urged to consult the example handlers at the end of this 
appendix, which illustrates the operation of device handlers. 

H.1.4 Issuing Programmed Requests at the Interrupt Level 

Programmed requests from interrupt routines must be preceded by a 
.SYNCH call. This ensures that the proper job is running when the 
programmed request is issued. The .SYNCH call assumes that nothing 
has been pushed onto the stack by the user program between the .INTEN 
call and the .SYNCH call. On successful completion of a .SYNCH, RO 
and Rl have been saved and are free to be used. R4 and R5 are no 
longer free, and should be saved and restored if they are to be used. 

Programmed requests that require USR action should not be called from 
within interrupt routines. 
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H.1.5 Setting Up Interrupt Vectors 



34,36 


2 words 


40 


1 word 


42 


1 word 


44 


1 word 


46 


1 word 


50 


1 word 



Devices for which no RT-11 handler exists must be serviced by the user 
program. For example, no LPS device handler exists? to use an LPS, 
the user must write his own interrupt service routine. It is the 
responsibility of the program to set up the vector for devices such as 
this. The recommended procedure is not to simply move the service 
routine address and 340 into the desired vector; rather, this 
operation must be preceded by a .PROTECT macro call. The .PROTECT 
ensures that neither the other job nor the monitor already has control 
of that device. If the .PROTECT is successful, the vector can be 
initialized. 



H.1.6 Using .ASECT Directives in Relocatable Image Files 

With some exceptions, user programs in REL format should not contain 
.ASECT directives. The Linker does not allow .ASECTs above 1000 when 
the /R switch is used; in general all .ASECTs below 1000 are ignored. 
The exceptions are: 

TRAP instruction vector 

program start address 

stack start address 

job status word 

USR swap address 

program high limit j 

.ASECTs may be used to initialize any of the above locations providing | 
they are not in a program to be linked for the foreground. To initial- I 
ize any other locations between 0-777, the user should first .PROTECT 
the appropriate words, and then move the correct values into place. 

A job which contains overlays cannot have any .ASECTs at all, 
including those listed above. If overlays are to be used, the program 
start address should be set up as the argument for the .END statement; 
the other values can be initialized when the program is initiated. 

Since .ASECTs into device vectors are not permitted, the user program 
must initialize vectors at runtime. To do this, execute a .PROTECT 
for the specified vector. If the .PROTECT is successful, it is safe 
to move values into the vectors. If the .PROTECT request fails, it is 
an indication that the vector is already in use by another job and 
that it is not safe to initialize the vector. 



H.1.7 Using .SETTOP 

Proper use of .SETTOP is vital to preserve system integrity. Since 
RT-11 employs no hardware memory protection, the user must at all 
times observe the value returned in R0 from a .SETTOP request. It 
must never be assumed that the value requested by the program is the 
value returned by .SETTOP. 
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The monitor loads foreground .programs into a memory partition just 
large enough for the program plus job header (impure area) . No free 
space is available for a .SETTOP request, which may cause some pro- 
grams to fail, in particular, any FORTRAN program. Free space may 
be provided within the program using, for example, the .BLKW directive,, 
or it may be allocated at runtime using the FRUN /N switch. Appendix 
G, Section G.l, explains how to allocate more space for FORTRAN pro- 
grams . 



H.1.8 Making Device Handlers Resident 

Device handlers used by a foreground job must be made permanently 
resident with a LOAD command. A .FETCH from a foreqround job of a 
non-resident handler will cause a fatal error and abort the job. 
Therefore, a program written specifically for the foreground, or one 
that is to be run in either foreground or background partitions, should 
first execute a .DSTATUS on the device, to determine if the handler is 
resident, before issuing a .FETCH directive. 



H.2 DEVICE HANDLERS 

This section deals with the device handlers which are part of the 
RT-11 System, Version 2. Any device dependent information or general 
information required by the user is contained here. No mention of a 
handler implies that no special conditions must be met to use that 
device (all disks except diskette and DECtape are in this category, 
and therefore are not covered here) . 
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Differences Between VI and V2 Device Handlers 

User-written device handlers must, in all cases, conform to the 
standard practices for Version 2. Since the last word of a device 
handler is used by the monitor, the user should be sure to include one 
extra word at the end of his program when indicating the size of the 
handler. 

The differences between Version 1 and Version 2 handlers include the 
following: 

A. Header Words 

In Version 1 handlers, the third header word was taken to be 
the priority at which the device interrupt was taken. In 
Version 2, this word should be 340, indicating that the 
interrupt should be taken at priority level 7. (The priority 
level is set to 7 by the FETCH code regardless of what appears 
in the third word of the header.) 

B. Entry Conditions 

It is not necessary to save/restore registers when the 
handler is first entered, although to do so is not harmful. 
In Version 1, it was necessary to preserve R5 on first 
entering the handler. 

C. Interrupt Handling 

When an interrupt occurs, Version 2 handlers must execute an 
INTEN request or its equivalent. (This was not necessary in 
Version 1.) On return from the .INTEN, R4 and R5 may be used 
as scratch registers. Device handlers may not do EMT 
requests without executing a .SYNCH request. (Refer to 
Chapter 9 for explanations of .INTEN and .SYNCH.) 

The handler must return from an interrupt via an RTS PC 
rather than an RTI, as in Version 1. The .INTEN request 
essentially reenters the handler via a JSR PC, and thus the 
RTS PC returns control to the monitor, which executes the RTI 
when appropriate. 

When the transfer is complete, the handler must exit to the 
monitor to terminate the transfer and/or enter a completion 
routine. When return is made to the monitor, R4 should point 
to the fifth word of the handler. 

D. Abort Entry Point 

All Version 2 device handlers must have an abort entry point 
to which control is transferred on CTRL C, hard .EXIT, or 
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. HRESET. This abort entry point is located one word before 
the interrupt service routine entry point and must contain a 
BR instruction to abort code. The abort code must stop the 
device operation and then exit through the jump into the com- 
pletion code in RMON. Some devices, such as moving head 
disks, cannot be effectively stopped. In this case, it is 
permissible for the abort code to consist of just an RTS PC 
instruction. Examples are the RK05 and RPR02/RP03 device 
drivers. See Section H.3 for examples of device handlers 
with abort entry code. 

The user is urged to refer to the example handlers enclosed. The same 
general techniques can be used to interface user device handlers. 

H.2.1 PR (High-Speed Paper Tape Reader) 

Unlike the PR handler for Version 1, the Version 2 PR handler does not 
print a t on the terminal when it is entered for the first time. The 
tape must be in the reader when the command is issued, or an input 
^ff« r t,o CCU £ S * This Prohibits any two-pass operations from being done 
using PR. For example, linking and assembling from PR will not work 
properly; an input error will occur when the second pass is 
initiated. The correct (and recommended) procedure is to use PIP to 
transfer the paper tape to disk or DECtape, and then perform the 
operation on the transferred file. 

H.2.2 TT (Handler for Console Terminal) 

3 e hSSj? 'Se^f bS US6d aS a P^Pfc-al «evice by using the 
1. A t is typed when the handler is ready for input. 

2 ' SSi 8 Can b ! mBi M to specify the end of input to TT. No 
carriage return is required after the CTRL Z. If CTRL Z is 
not typed the TT handler accepts characters until the worl 
count of the input request is satisfied. 

3. CTRL 0, struck while output is directed to TT, causes an 

entire output buffer (i.e., all characters currently queue!? 
to be ignored. This is somewhat different than the normal 
action of CTRL while at the console. normal 

4 * Ll^ft °l^ C S ^ rUCk While typln « ln P ut t° TT causes a 
ptr? £ f° S r n i t0r * If OUtput is directed to TT, a double 
CTRL C is required to return to the monitor if F/B is 

CreSulrJ^n^ ^ n ? lltor ±S ™™ in *' °nly * single CTRL ? 
is required to terminate output. 

5 * backarouSf le L Ca 2 b ?- ln ""VS* ° nly ° ne * oh ^aground or 
background) at a time, and for only one function (input or 
output at a time. The terminal communication for the -job 
not using TT is not affected at all. 3 

6. The user may type ahead to TT; the input ring buffer is 
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8. If a job sends a buffer to TT for output and then does a 
.TTYOUT or a .PRINT, the output from the latter is delayed 
until the handler completes its transfer. If a TT output 
operation is started when the monitor's terminal output ring 
buffer is not empty (i.e., before the print-ahead is 
complete) , the handler supersedes the ring buffer until its 
transfer is complete. 

H.2.3 CR (Card Readers) 

The card reader handler can transfer data either as ASCII characters 
in DEC 026 or DEC 029 card codes (Section H.4) , or as column images 
controlled by the SET command (see Chapter 2) . In ASCII mode (SET CR 
NOIMAGE) , invalid punch combinations are decoded as the error 
character 134 (octal) — backslash. In IMAGE mode, no punch combination 
is invalid; each column is read as 12 bits of data right- justified in 
one word of the input buffer. The handler continues reading until the 
transfer word count is satisfied or until a standard end-of-file card 
is encountered (12-11-0-1-6-7-8-9 punch in column 1; the rest of the 
card is arbitrary). On end-of-file, the buffer is filled with zeroes 
and the request terminates successfully; the next input request from 
the card reader gives an end-of-file error. Note that if the transfer 
count is satisfied at a point which is not a card boundary, the next 
request continues from the middle of the card with no loss of 
information. If the input hopper is emptied before the transfer 
request is complete, the handler will loop until the hopper is 
reloaded and the "START" button on the reader is pressed again. The 
transfer will then continue until completion or until another hopper 
empty condition exists. End-of-file is not reported on the hopper 
empty condition. The handler will loop if the hopper empties during 
the transfer regardless of the status of the SET CR HANG/NOHANG 
option. No special action is required to use the card reader handler 
with the CM-11 mark sense card reader. The program should be aware of 
the fact that mark sense cards may contain less than 80 characters. 
Note also that when the CR handler is set to CRLF or TRIM and is 
reading in IMAGE mode, unpredictable results may occur. 

j H.2.4 MT/CT (Magtape (TM11, TU16) and Cassette (TA11) ) 

These devices have a file structure which differs from the common 
RT-11 structure. Each handler is capable of entirely supporting its 
own file structure and of allowing RT-11 users full access to the 
devices without being totally familiar with them. 



H.2.4.1 General Characteristics - Both magtape and cassette can 
operate in two possible modes: "hardware" mode and "software" mode. 
These names refer to the type of operation which can be performed on 
the device at a given time. Software mode is the normal mode of 
operation and the mode used when accessing the device through any of 
the RT-11 system programs. In software mode, the handler 
automatically attends to file headers and uses a fixed record length 
to transfer data (256-word for magtape; 64-word for cassette) . 

Hardware mode allows the user to read or write any format desired, 
using any record size. In this mode, the word count is taken as the 
physical record size. 
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ers 



nonfile-structured lookup must be plrfSrmld." (A^nonf ile^ructu'red 3 
i * L 1S ? l00kup in which the f irst word of the f ilenamf is nni i ) 
J? n'S'V* ?* TM11 handl6r haS been »odi?ieS(af described in the 

somewhat differently. Re fer ^h f R^ Uef ^ .^Eng^* 

NOTE 

Due to the size of the TM11 and TJU16 
magtape handlers, users who have 
systems with less than 20K, and who 
have loaded both handlers simultane- 
ously, may experience user memory re- 
strictions. 

In software mode, the following functions are permitted: 



ENTER 
LOOKUP 



Open new file for output 

Open existing file for input and/or output 
DELETE - Delete an existing file on the device 
CLOSE - Close a file which was opened with ENTER or LOOKUP 
READ/WRITE - Perform data transfer requests 

In ENTER, LOOKUP, and DELETE, an optional file count parameter can be 
specified for use with magtape or cassette. Its meaning is as 
follows : 

Count Argument Meaning 

=0 A rewind is done before the operation. 

>° No rewind is done. The value of the count is 
taken as a limit of how many files to skip before 
performing the operation (e.g., a count of 2 will 
skip over, at most, one file. A count of 1 will 
not skip at all) . 

<° A rewind is done. The absolute value of the switch 
value is then used as the limit. 

If the file indicated in the request is located before the limit is 
exhausted, the search succeeds at that point. 

As an example, consider: 

.LOOKUP *AREA,#0,#PTR,*5 
BCS At 

t 

AREAt ,BLKW 10, 
p TR| .RAD50 /MT0/ 

.RAD50 /EXAMPLMAC/ 

In this case, the file count argument is +5, indicating that no rewind 
is to be done and that MTO is to be searched for the indicated file 
(EXAMPL.MAC) . If the file is not found after four files have been 
skipped, or if an end-of-tape occurs in that space, the search is 
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stopped, and the tape is positioned either at the e n d -° f - ta P e ,^? T) ° r 
at the start of the fifth file. If the named file is found within the 
five files, the tape is positioned at its start. If the EOT is 
encountered first, an error is generated. 

As another example: 

.LOOKUP #AREA,#0,#PTR,#-5 

This performs a rewind, and then uses a file count of five in the same 
way the above example does. 

H.2.4.2 Handler Functions 
1. LOOKUP 

If the filename (or the first word of the filename) is null, 
the operation is considered to be a nonf ile-structured 
LOOKUP. This operation puts the handler into hardware mode. 
A rewind is automatically done in this case. 

If the filename is not null, the handler tries to find the 
indicated file. LOOKUP uses the optional file count as 
illustrated above. Only software functions are allowed. 



2 . DELETE 

DELETE will delete a file of the indicated name from the 
device. DELETE also uses the file count argument, and can 
thus do a delete of a numbered file as well as a delete by 
name. When a file is deleted from MT or CT, an unused space 
is created there. However, it is not possible to reclaim 
that space, as it is when the device is random access. The 
unused spot will remain until the volume is re-initialized 
and rewritten. 

If a filename is not present, a nonf ile-structured DELETE is 
performed and the tape is zeroed. 

3. ENTER 

ENTER creates a new file of the indicated name on the device. 
ENTER uses the optional file count, and can thus ENTER a file 
by name or by number. If ENTER by name is done, the handler 
deletes any files of the same name it finds in passing. If 
ENTER by number is done, the indicated number of files is 
skipped, and the tape is positioned at the start of the next 
file. 

NOTE 

Care must be used in performing numbered 
ENTERS, as it is possible to ENTER a 
file in the middle of existing files and 
thus destroy any files from the next 
file to the end of the tape. 

It is also possible to create more than 
one file with the same name, since ENTER 



January 1976 H " 8 



F/B Programming and Device Handlers 



will only delete files of the same name 
it sees while passing down the tape. If 
an ENTER is done with a count greater 
than 0, no rewind is performed before 
the file is entered. If a file of the 
same name is present at an earlier spot 
on the tape, the handler cannot delete 
it. A nonf ile-structured ENTER 
performs the same function as a nonfile- 
structured LOOKUP but does not rewind 
the tape. Since both functions allow 
writing to the tape without regard to 
the tape's file structure, they should 
be used with care on a file-structured 
tape. 



4 . CLOSE 



CLOSE terminates operations to a file on magtape or cassette 
and resets the handler to allow more LOOKUPS, ENTERS, or 
DELETES. If a CLOSE is not performed to an ENTERed file, the 
end-of-tape mark will be missing and no new files can be 
created on that volume. In this case, the last file on the 
tape must be rewritten and CLOSEd to create a valid volume. 



5. READ/WRITE 

READ and WRITE are unique in that they can be done either in 
hardware or software mode. In software mode (file opened 
with LOOKUP or ENTER) , records are written in a fixed size 
(256 words for magtape, 64 words for cassette). The word 
count specified in the operation is translated to the correct 
number of records. On a READ, the user buffer is filled with 
zeroes if the word count exceeds the amount of data 
available. 

Following is a discussion of how the various parameters for 
READ/WRITE are used for magtape and cassette. 

a. Block Number 

For READ operations to magtape, the block number is 
used for random access (i.e., blocks need not be 
read sequentially from magtape). WRITE operations, 
however, disregard the block number and merely write 
the next sequential block. Block on either READ 
or WRITE causes the device to rewind to the start of 
the file. A subsequent WRITE will destroy all 
previous output to that file. 

For cassette, only sequential operations are 
performed. If the block number is 0, the cassette 
is rewound to the start of the file. Any other 
block number is disregarded. 
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b. Word Count. 



On a magtape READ, if the word count is 0, the block 
number is ignored and the next sequential record is 
read, no matter how big it is. 

NOTE 

Care must be taken when performing a 
magtape READ, because the READ will be 
done even if the record to be read is 
larger than the buffer allocated. 



On a magtape WRITE, if the 
256-word block is written. 



word count is 0, one 



If the word count for cassette is 
conditions are possible: 



, the following 



If the block number is non-zero, the operation is 
actually a file-name seek. The block number is 
interpreted as the file count argument, as discussed 
in the above example of LOOKUP. The buffer address 
should point to the RAD50 of the device and file to 
be located. This feature essentially allows an 
asynchronous LOOKUP to be performed. The standard 
LOOKUP request does not return control to the user 
program until the tape has been positioned properly, 
whereas this asynchronous version will return 
control immediately and interrupt when the file is 
positioned. 

The user may then do a synchronous, positively 
numbered LOOKUP to the file just positioned, thus 
avoiding a long synchronous search of the tape. 

If the block number is 0, a CRC (cyclical redundancy 
check) error occurs. 

Following is a description of the allowed hardware mode functions for 
the handlers, as well as examples of how to call them. In general, 
special functions are called by using the .SPFUN request; examples of 
usage follow each function. The special functions require a channel 
number as an argument. The channel must initially be opened with a 
non-file structured LOOKUP which places the handler in hardware mode. 

The general form of the .SPFUN request is: 

. SPFUN . are a , . chan , . code , . buf f , .went , . blk , . crtn 

where : 

.code is the function code to be performed. 

The request format is : 

R0 * .area: 



32 l.chan 

.blk 

.buff 

.went 

.code 37 7 
.crtn 
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1. Magtape Special Functions 



Rewind (Code ■ 373) - Rewinds the tape to the load point. 
This puts the unit into hardware mode (as does a nonfile- 
structured LOOKUP) where any of the other functions may 
be done. 

Sample Macro Call: 

The above performs a synchronous rewind on channel 
(i.e., control will not return before the tape is 
positioned). An asynchronous rewind could be done with: 

.STUN *APfcA,#0,#-J73,#0.,,#CKTN f REWIND MJ, CHANNEL 

where CRTN is a completion routine to be entered when the 
operation is finished. The other arguments are not 
required for this call. 



b. Write End-of-File (Code - 377) - This request writes an 
end-of-file mark, thus terminating a file. 

Sample Macro Call: 

.SI-TUN *AP£A,#0,#577,*3|THIS IS THE SYNCHRONOUS FORM 
The asynchronous form is : 

.STUN *A»fcA,#0,(H77,*0,,,#CRTN|WRITE EOF ON 

>MT, CHANNEL 



Forward Space (Code = 376) - This function spaces forward 
the specified number of records and then stops, if the 
EOT or EOF is discovered before the count is exhausted, 
the tape stops there. Note that the number of records to 
space forward is contained in the word count argument, 
and the number passed should be the positive value of the 
desired number. 

Sample Macro Call: 

.STUN #APe;A,#0,*V7(>, #<*,#? (SPACE FORWARD 2 

fRECOROS, CHANNEL 

This spaces forward two records. 



d. Back Space (Code = 375) - This is similar to Forward 
Space except the tape is backed up by the indicated 
number of blocks. Again, the word count must be the 
positive value of the number to back up. 
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Sample Macro Call: 

This backs the tape up by two records. 

e. Write With Extended Gap (Code » 374) - This request is 
the same as any of the WRITE requests, except that a 
longer file gap is written between records. This can be 
used to get past bad spots on the tape. 

Sample Macro Call: 

.SPFUN *AREA,*0,#37«,#BUFF,#100.,#0 
This performs a synchronous write, while: 

.SPFUN *AREA,#0,#374,*BUFF,#100.,*l,#eRTN 

is asynchronous and goes to CRTN when the operation is 
complete. 



f. Offline (Code «■ 372) - This request sets the drive to an 
off-line state. The unit can only be set on-line by 
manual control. 

Sample Macro Call: 

.SHFUN *ARfcA,#0,#T7?,#0 

Since this in an instantaneous function, no asynchronous 
forms are required. 



Cassette Special Functions 

With exceptions noted, these requests are identical to those 
involving magtape. 

a. Rewind (Code = 373) - This request is identical to the 
rewind request for magtape, except that unless a 
completion routine is specified, control does not return 
to the user until the rewind completes. 

b. Last File (Code ■ 377)- This request rewinds the cassette 
and positions it immediately before the sentinel file 
(logical end-of-tape) . The macro call is the same as for 
magtape code 377. 

c. Last Block (Code = 376) - This request rewinds one record. 
See the magtape code 376 for a sample macro call. 

d. Next File (Code - 375) - This request spaces the cassette 
forward to the next file. 

e. Next Block (Code - 374)- This request spaces the cassette 
forward by one record. 
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f. Write Pile Gap (code » 372) - This request terminates a 
file written by the user program when in hardware mode. 

Sample Macro Call: 

.S^FUN #APfcA,#0, #■??«!, #0 
This writes a file gap synchronously, while: 

,5^FUN #ABfcA,#0,#!!7?,#(d,,,#l 

or 

.S^FUN *APfc,A,#(0,#V?, #0,, ,*CRTN 
performs asynchronous write file gap operations. 

H.2.4.3 Magtape and Cassette End-of-File Detection - Since magtape 
and cassette are sequential devices, the handlers for these devices 
cannot know in advance the number of blocks in a particular file, and 
thus cannot determine if a particular read request is attempting to 
read past the end of the file. User programs can use the following 
procedures to determine if the handlers have encountered end-of-file 
in either software or hardware mode. 

In software mode, if end-of-file is encountered, magtape and cassette 
handlers will set the end-of-file bit (bit 13) in the channel status 
word. The next read attempted on that channel wil return with the carry 
bit set and with the EMT error byte (absolute location 52) set to in- 
dicate an attempt to read past end-of-file. To avoid having magtape 
or cassette files appear one block longer than they really are, user 
software should check the end-of-file bit in the channel status word 
after a magtape or cassette read completes. If the bit is set, this 
indicates that the read just completed encountered end-of-file. 

The following example demonstrates the procedure in software mode: 

.MCALL ..V2..,.REG0fcP,.GTJB, .LOOKUP, .RE AD W 
.REGDEF 

CSWEOFagMBQ IEN0 OF FILE BIT IN CHANNEL STATUS WORD 

ERRWP0«32 »EMT ERROR WORD 

CHNL-l » I/O CHANNEL # 



„GTJe #LIST»#JOBARG jGET JOB PARAMETERS 

..LOOKUP* #AREA,#CHNL,#FILNAM ILOOKUP MAGTAPE OR CASSETTE FILE 



.REARW #AREA,#CHNL,#BUFF,#400,BLKNUM fREAO A BLOCK 

BCS EMTERR ICHECK FOR ERROR 

MOV J0BARG+«. # R1 IGET POINTER TO I/O CHANNEL SPACE 

I (CHANNEL SPACE IS 5 WORDS PER CHANNEL 

I8EGINNING WITH CHANNEL (5). 
BIT #CSWEQF,CHNL*i0. (Rl) IIS THE EOF BIT SET FOR THIS CHANNNIL? 
BNE EOF f IF ME - YES - EOF ENCOUNTERED ON THIS READ 
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EOF! 



»EN0 OF FILE CODE 



FIL.NAMI .RAO30 'MT0FIL.N AMEXT' »0" .»*D5"0 'CT0FILNAMEXT * 

AREAt ,BLKW 10 

LIST! .BUW 2 

J09ARI3J .8LKW 10 » JOB PARAMETERS STORED HERE 



In hardware mode, the cassette and magtape handlers do not report end- 
of~file, as they do in software mode. The best way that user programs 
may determine if a magtape read has encountered a tape mark or if a 
cassette read has encountered a file gap is to check the device status 
registers after each hardware mode read is complete. 

Examples are: 

For TM11/TMA11 Magtape 



MTS«Ua58SZI 
MTC«MTS+2 

MTSEOF-40000 
MT8EOT«2000 



JTMH STATUS REGISTER 
ITM1J COMMAND REGISTER 
>E0F BIT IN MTS 
IEOT BIT IN MTS 



.REAOW #AREA,#CHNL.#8LiFF,#U00,BlKNUM 



>REA0 A BLOCK FROM MT 



BCS EMTERR 

TST MMTC 

BPL NOEWR 

BIT *MT8E0F,MMTS 

BNE EOF 



>CHECK ERRORS 

IERR0R BIT SET IN COMMAND REGISTER? 

(IF PL - NO 

»VES - WAS IT EOF fTAPE MARK]? 

fIF NE - VES - 00 END OF FILE PROCESSING 



EOFI 



IMT EOF ENCOUNTERED 



For Cassette 



TACS«177500 

TAEOF««000 

TAEQT'20000 



ITA11 CONTROL AND STATUS REGISTER 
>E0F BIT IN TACS 
IEOT BIT IN TACS 



.REAOW #AREA,#CHNLr#8UFF,#fl00,BLKNUM 



IREAO FROM CT 



BCS EMTERR 

TST MTAC3 

BPL NQERR 

BIT #TAEOF,MTACS 

BNE EOF 



ITEST ERRORS 

»E»R0R BIT SET IN TACS? 

I IF PL - NO 

JVES - WAS IT END OF FILE? 

IIP NE - YES 



EOFJ 



ICASSETTE END OF FILE ENCOUNTERED 
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If desired, both the EOF and EOT bits could be checked: 

BIT #MTSEOF+MTSEOT,*#MTS »MT EOF OR EOT? 
or 

BIT #TAEOF+TAE0T»*#TACS ICT EOF OR EOT? 

H.2.5 DX (RXO] Diskette) I 

The .SPFUN request is used to allow reading and writing of absolute 
sectors on the RX01 diskette. An RX01 disk contains 77 tracks, | 
each having 26 sectors, for a total of 2002 sectors. Each sector is 
64 words long. RT-11 normally reads and writes groups of 4 sectors. 
Sectors may be accessed individually using the .SPFUN request as 
follows: 

.SPFUN .area, .chan, .code, .buff, .went, .blk, .crtn 

where : 

.code is the function code to be performed (377 for READ 
physical, 376 for WRITE physical, 375 for WRITE 
physical with deleted data mark) 

.buff is the location of a 6 5-word buffer? word 1 is the 
flag word and is normally set to (if set to 1, 
a READ on physical sector containing deleted data 
mark is indicated) ; words 2-65 are the 64-word area 
to read (or write) the absolute sector 

•went is the absolute track number, through 76, to be 
read (or written) 

.blk is the absolute sector number, 1 through 26, to be 
read (or written) 

The diskette should be opened with a nonfile-structured LOOKUP. Note I 
also that the .buff, .went, and .blk arguments have different meanings 
when used with diskette. | 



Sample Macro Call: 



.SPFUN *RHLIST,#1,#"*7T,#BIIFF,*0,#?,#0 

rPFRFQBM A SYNCHRONOUS 3FCT0* 
FRFAO FROM TRACK Z, RECTOR 7 
ICTHF VOLUME I«) INTO THF 
»fe«!-W0B0 ARE* *\jrr 



RT-11 currently provides only one diskette handler as part of the 
system. The user may optionally install a second diskette handler by 
following the procedures outlined in Chapter 4 of the RT-11 System 
Generation Manual. 
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H.4 DEC 026/DEC 029 CARD CODE CONVERSION TABLE 

Card codes in the following table are broken down by zone punch. 
Except where noted , all codes apply to both DEC 026 and DEC 029 punched 
cards. 



Table H-l 
Card Code Conversions 



Zone 


Digit 


Octal 


Character 


Name 


none 












none 


040 




SPACE 




1 


061 


1 


digit 1 




2 


062 


2 


digit 2 




3 


063 


3 


digit 3 




4 


064 


4 


digit 4 




5 


065 


5 


digit 5 




6 


066 


6 


digit 6 




7 


067 


7 


digit 7 


12 










(DEC 029) 


none 


046 


& 


ampersand 


(DEC 026) 




053 


+ 


plus sign 




1 


101 


A 


upper case A 




2 


102 


B 


upper case B 




3 


103 


C 


upper case C 




4 


104 


D 


upper case D 




5 


105 


E 


upper case E 




6 


106 


F 


upper case P 




7 


107 


G 


upper case G 


11 












none 


055 


- 


minus sign 




1 


112 


J 


upper case J 




2 


113 


K 


upper case K 




3 


114 


L 


upper case L 




4 


115 


M 


upper case M 




5 


116 


N 


upper case N 




6 


117 





upper case 





7 


107 


P 


upper case P 




none 


060 





digit 




1 


057 


/ 


slash 




2 


123 


S 


upper case S 




3 


124 


T 


upper case T 




4 


125 


U 


upper case U 




5 


126 


V 


upper case V 




6 


127 


w 


upper case W 


8 


7 


130 


X 


upper case X 


none 


70 


8 


digit 8 




1 


140 


- 


accent grave 


(DEC 029) 


2 


072 


; 


colon 


(DEC 026) 




137 


■*- 


backarrow 

(underscore; 


(DEC 029) 


3 


043 


# 


number sign 



(continued on next page) 
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Table H-l (Cont.) 
Card Code Conversions 



Zone 


Digit 


Octal 


Character 


Name 


(DEC 026) 




075 


= 


equal sign 




4 


100 


@ 


commercial "at" 


(DEC 029) 


5 


047 


t 


single quote 


(DEC 026) 




136 


+ 


uparrow 

(circumflex) 


(DEC 029) 


6 


075 


= 


equal sign 


(DEC 026) 




047 


i 


single quote 


(DEC 029) 


7 


042 


1! 


double quote 


(DEC 026) 
9 




134 


\ 


backslash 


none 


071 


9 


digit 9 




2 


026 


Ctrl - V 


SYN 




7 


004 


ctrl - D 


EOT 


12-11 












none 


174 


1 


vertical bar 




1 


152 


1 


lower-case J 




2 


153 


k 


lower-case K 




3 


154 


1 


lower-case L 




4 


155 


m 


lower-case M 




5 


156 


n 


lower-case N 




6 


157 


o 


lower-case 




7 


160 


P 


lower-case P 


12-0 












none 


173 


{ 


open brace 




1 


141 


a 


lower-case A 




2 


142 


b 


lower-case B 




3 


143 


c 


lower-case C 




4 


144 


d 


lower-case D 




5 


145 


e 


lower-case E 




6 


146 


f 


lower-case F 




7 


147 


g 


lower-case G 


12-8 












none 


110 


H 


upper-case H 


(DEC 029) 


2 


133 


[ 


open square bracket 


(DEC 026) 




077 


? 


question mark 




3 


056 


. 


period 


(DEC 029) 


4 


074 


< 


open angle bracket 


(DEC 026) 




051 


) 


close parenthesis 


(DEC 029) 


5 


050 


( 


open parenthesis 


(DEC 026) 




135 


] 


close square bracket 


(DEC 029) 


6 


053 


+ 


plus sign 


(DEC 026) 




074 


< 


open angle bracket 




7 


041 


! 


exclamation mark 


12-9 












none 


111 


I 


upper-case I 




1 


001 


Ctrl - A 


SOH 




2 


002 


Ctrl - B 


STX 




3 


003 


ctrl - C 


ETX 




5 


011 


ctrl - I 


HT 




7 


177 




DEL 



(continued on next page) 
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Table H-l (Cont. ) 
Card Code Conversions 



Zone 


Digit 


Octal 


Character 


Name 


11-0 


















none 


175 


I 




close brace 






1 


176 






tilde 






2 


163 


s 




lower-case S 






3 


164 


t 




lower-case T 






4 


165 


u 




lower-case U 






5 


166 


V 




lower-case V 






6 


167 


w 




lower-case W 






7 


170 


X 




lower-case X 


11-8 


















none 


121 


Q 




upper-case Q 


(DEC 


029) 


2 


135 


] 




close square bracket 


(DEC 


026) 




072 


: 




colon 






3 


044 


$ 




currency symbol 






4 


052 


* 




asterisk 


(DEC 


029) 


5 


051 


) 




close parenthesis 


(DEC 


026) 




133 


c 




open square bracket 


(DEC 


029) 


6 


073 


3 




semi-colon 


(DEC 


026) 




076 


> 




close angle bracket 


(DEC 


029) 


7 


136 


i 




uparrow 

(circumflex) 


(DEC 


026) 




046 


& 




ampersand 


11-9 


















none 


122 


R 




upper-case R 






1 


021 


Ctrl - 


Q 


DC1 






2 


022 


Ctrl - 


R 


DC2 






3 


023 


Ctrl - 


S 


DC3 






6 


010 


Ctrl - 


H 


BS 


0-8 


















null 


131 


Y 




upper-case Y 


(DEC 


029) 


2 


134 


\ 




backslash 


(DEC 


026) 




073 


3 




semi-colon 






3 


054 


3 




comma 


(DEC 


029) 


4 


045 


% 




percent sign 


(DEC 


026) 




050 


( 




open parenthesis 


(DEC 


029) 


5 


137 


-*- 




backarrow 

(underscore) 


(DEC 


026) 




042 


11 




double quote 


(DEC 


029) 


6 


076 


> 




close angle bracket 


(DEC 


026) 




043 


# 




number sign 


(DEC 


029) 


7 


077 


9 




question mark 


(DEC 


026) 




045 


% 




percent sign 


0-9 


















null 


132 


Z 




upper-case Z 






5 


012 


Ctrl - 


J 


LF 






6 


027 


Ctrl - 


W 


ETB 






7 


033 






ESC 


9-8 


















4 


024 


Ctrl - 


T 


DC4 






5 


025 


ctrl - 


U 


NAK 






7 


032 


Ctrl - 


Z 


SUB 



(continued on next page) 



H-25 



F/B Programming and Device Handlers 

Table H-l (Cont. ) 
Card Code Conversions 



Zone 


Digit 


Octal 


Character 


Name 


12-9-8 












3 


013 


Ctrl - K 


VT 




4 


014 


Ctrl - L 


FF 




5 


015 


Ctrl - M 


CR 




6 


016 


Ctrl - N 


SO 




7 


017 


Ctrl - 


SI 


11-9-8 












none 


030 


Ctrl - X 


CAN 




1 


031 


Ctrl - Y 


EM 




4 


034 


Ctrl - \ 


FS 




5 


035 


Ctrl - ] 


GS 




6 


036 


Ctrl - -t- 


RS 




7 


037 


Ctrl - 


US 


0-9-8 












5 


005 


Ctrl - E 


ENQ 




6 


006 


Ctrl - P 


ACK 




7 


007 


Ctrl - G 


BEL 


12-0-8 


none 


150 


h 


lower-case H 


12-0-9 


none 


151 


1 


lower-case I 


12-11-8 


none 


161 


q 


lower-case Q 


12-11-9 


none 


162 


r 


lower-case R 


11-0-8 


none 


171 


y 


lower-case Y 


11-0-9 


none 


172 


z 


lower-case Z 


12-11-9-8 












1 


020 


Ctrl - P 


DLE 


12-0-9-8 












1 


000 




NUL 
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APPENDIX I 
DUMP 



RT-11 DUMP is a program which outputs to the console or lineprinter 
all or any part of a file in octal words, octal bytes, ASCII 
characters and/or RAD50 characters. DUMP is particularly useful for 
examining data such as directories or files. 



1.1 CALLING AND USING DUMP 

DUMP is called using the monitor command: 

R DUMP 

in response to the dot printed by the Keyboard Monitor. The name of 
the file which is to be output is entered as follows in response to 
the asterisk printed by the Command String Interpreter: 

de v : outpu t=de v : input /s 



where : 



dev: 



output 



input 



/s 



represents any valid device specification (line printer 
is default for output if no output file is designated. 
The default can be changed; refer to Chapter 4 of the 
RT-11 System Generation Manual . 

represents the filename and extension assigned to the 
output file. The default extension for file-structured 
output is .DMP. 

represents the input source filename and extension. 

NOTE 

Input files residing on magtape and 
cassette must have been written under 
the RT-11 system; magtape and cassette 
files written under other 
environments cannot be dumped. 

represents one or more of the switches listed in Table 
1-1. 



system 



Type CTRL C to halt DUMP at any time and return control to the 
monitor. To restart DUMP type R DUMP or the REENTER command in 
response to the monitor's dot. 
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I. 1.1 DUMP Switches 

The following switches can appear in the command string for DUMPs 



Table 1-1 
DUMP Switches 



Switch 



/B 

/E:n 

/G 

/N 

/0:n 

/S:n 

/W 

/X 



Meaning 



Output octal bytes 

End output at block number n 

Ignore input errors 

Suppress ASCII output 

Output only block number n (same as /E:n„ 
/S:n) 

Start output with block number n 

Output octal words 

Output RAD50 characters 



If neither /W nor /B is given, /W is assumed. ASCII characters are 
always dumped unless /N is given. The number n is an octal block 
number. 

If an input filename is given, block numbers are relative to the 
beginning of the file to which the block belongs. If not, block 
numbers are absolute block numbers on the device (i.e., the physical 
block numbers on the corresponding device) . 



1.1.2 Examples 

The following are two examples of DUMP. /B is used in the first 
example to output octal bytes of the file SQRT.FTN into a file called 
DIF.DMP on device DTI. 

R DUMP 
*DT1:DIF=SQRT. FJU/B 

If DIF.DMP is then listed on the line printer (using PIP) , it appears 
as follows: 

BLOCK NUMttgR 01000 

000/ 001 000 096 000 001 000 011 261 214 072 190 000 000 000 001 297 

1 I M / 

020/ 224 017 110 001 000 010 202 292 304 037 110 004 210 000 374 252 

..H.,.2*0,H,,,0* 
040/ 016 024 110 0H4 006 000 033 294 217 193 110 004 000 000 012 001 

M 5 H 

060/ 000 036 000 001 000 084 253 100 070 100 004 000 000 123 263 024 

100/ 299 190 001 000 000 000 000 000 000 000 003 000 000 032 001 000 
• H ..... , ....*•• t 
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120/ 016 000 004 000 007 000 000 000 000 000 000 000 348 001 000 010 

F 

140/ 000 009 000 000 000 067 011 070 371 000 000 167 001 000 014 000 

7 k> Y W 

160/ 004 000 004 006 054 253 100 070 226 000 000 000 000 000 000 000 

200/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 

220/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 

240/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 

260/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 

300/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 

320/ 000 000 090 000 000 000 000 000 000 000 000 000 000 000 000 000 

340/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 

360/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 

400/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 

420/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 
440/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 

460/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 
900/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 
520/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 
940/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 
560/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 
600/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 
620/ 000 000 000 000 000 900 000 000 000 000 000 000 000 000 000 000 

• ••••••••••••••a 

640/ 090 000 000 090 000 000 000 000 000 000 000 000 000 000 000 000 

660/ 090 000 000 090 000 000 000 000 000 000 000 000 000 000 000 000 

700/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 

720/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 

740/ 090 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 



760/ 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 
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The second example illustrates the use of /X to output RAD50 and 

octal values for locations in the file. The numbers in the left 

column represent the byte displacement. ASCII characters are printed 

in the far right hand column (dot represents a non-printing 
character) : 

. R DUMP 
*RK1:L1NK0. FES/X 

BLOCK NUMBER 0000 

000/ (9271011 044524 046124 004505 052122 044514 045516 051x940 *,, TITLE . RTLI NK R* 

QNY K/L LMT ASM MSZ K/D LAB MEX 

020/ 047517 020124 047504 042504 020040 054040 031460 030455 *00T CODE X03-1* 

LIW 6F0 L$* *CL EEX HO HGX G4/ 

040/ 006406 035412 051040 026524 030461 046040 047111 042513 *6.,f RT-lt LlNKE* 

BQV IQ4 MEX GJO 043 LGH LUA KCS 

090/ 006522 039412 042040 041505 030455 026461 051H7 046114 *K.,; 0EC-1 1-URLL* 

BEJ IQ4 J6 J0U Q4/ Gil MFl LHL 

100/ 026501 026502 040514 005015 020073 040515 020131 032461 *A.B»LA,.I MAY 15* 

GlY ill JQ6 AXM EFK JQ7 EGA HT3 

120/ 020054 034461 032067 005015 020073 050105 020057 04/105 *, 1974..; EP/ £N* 

Et6 1FA HNG AXM EFK Li/ EE9 LT7 

140/ 040510 041516 042105 041040 020131 043512 005015 005015 *HANCEQ BY JG....* 

JU2 J00 J67 JWH EGA KPJ AXM AXM 

160/ 006473 035412 041440 050117 05U31 043511 052110 024040 *t,,t COPYRIGHT C* 

BOS IQ4 J/X L39 MGA KPI MSP FP2 

200/ 024503 024040 034461 032067 006451 035412 006440 035412 *C) (1974)..! ..)• 

MC PP8 IFA HNG BDI 104 BO 194 

220/ 042040 043511 0521H 046101 042440 052521 050111 042515 * DIGITAL E9UIPME* 

J6 KPI M3G LHA KBP MZA L33 KCU 

240/ 052110 041440 051117 047520 040522 044524 047117 005015 *NT CORPORATION.,* 

MSV J/X MFl USX J«6 K/L LUG AXM 

260/ 020073 040515 047131 051101 026104 046440 051501 040523 *} MAYNAROi MA58A* 

fcFK 407 LUU MFQ GCL LMX ML3 JRC 

300/ 044103 051525 052tu5 051524 030040 033461 032065 003015 #ChUSETT9 01754..* 

KV3 NMM MSM MML G, M3I HNE AXM 

320/ 006473 039412 052040 042510 044440 043116 051117 040515 *l..1 THE INFQRMA* 

BOS iQ4 MRP KCP K, KI8 MFl JQ7 

340/ 044324 047117 044440 020116 044124 051511 042040 041517 *TlON In THIS DOC* 

K/L LUG K, EF0 KV6 MMA J6 J0t 

360/ 046529 047105 020124 051511 051440 041125 042912 052103 *UmENT 19 SUBJECT* 

UN7 LT7 EF6 MMA ML JXU KCR MSK 

400/ 052040 006517 039412 041440 040910 043516 020105 044527 * TO..; CHANGE Ml* 

MRP BEG 104 J/X JQ2 KPN EFU K/0 

420/ 044124 052517 020124 047516 044524 042503 040440 042H6 *TH0UT NOTICE ANO* 

xve my» ire liv k/l kck JP2 J7f 

440/ 091440 047510 046125 020104 047516 020124 042502 041440 * SHOULD NOT BE C* 

ML L9P LHU EFT L»V EP6 KCJ J/X 

460/ 047117 052123 052522 042105 005015 020C73 051501 040440 *UnSTRUEQ..» AS A* 

LUG M9S MZB J67 AXM 6FK ML3 JP2 

500/ 041440 046517 044515 046524 047109 020124 054502 042040 * COMMITMENT BY 0* 

J/X LNl K/fc LN6 LT7 EF6 NKJ J6 

520/ 043311 040511 020124 050505 044525 046520 047105 020124 *ISI AT EQUIPMENT • 

KPI JQ3 EF6 M E K/m LN2 LT7 EF6 

540/ 047303 090122 05U17 052101 0473H 027116 009015 020073 ^CORPORATION. . , J * 

L»K L4S MFl MSI L*Q GPN AXM EFK 

960/ 042304 020103 051501 052523 042515 020123 047516 051040 *0EC AS9UMES NO R* 

KCL 6FS ML3 MZC KCU EPS LSV M£X 

600/ 051509 047920 051516 041111 0461U 052111 020131 047506 *EsPONSIbILlTY FO* 

ML7 L«X MMF JXI LHI M3U EGA L»* 

620/ 020122 047101 020131 051109 047522 051522 052040 040510 *H ANY ERRORS THA* 

fcF« LT3 EGA MFU LSZ MMJ MRP J02 

640/ 006924 035412 046440 054501 040440 050120 040505 020122 *T..» MAY APPEAR * 

BEL IQ4 LMX NKI JP2 L4 JO/ EF4 
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060/ 047111 058(340 044510 020123 047904 052503 042515 052116 *IN THIS DOCUMENT* 

LUA MRP K/ EF5 1*1 MYJ KCU MSV 

700/ 00C4QO 035412 005015 020073 044124 051511 051440 043U7 *...»..; THIS SOF* 

BON IQ4 AXW EFK KV6 MMA ML, KI9 

720/ 053524 05U01 020105 051511 043040 051125 044516 044123 *T*ARE IS FURNISH* 

M06 MFS fcFU MIA KH2 MF7 K/F KV5 

740/ 0421U5 052040 020117 052520 041522 040510 042523 020122 *E0 TO PURCHASER * 

J07 M«P EF1 M2 J04 JQ2 KCJ EF4 



760/ 047125 042504 (920122 006501 035412 046043 041511 0471*55 *UnQER A „ , j LlCEN* 
UUM KCU bF4 d03 IQ4 LGH J0Y LT7 



1.2 DUMP ERROR MESSAGES 

The following errors may occur when using DUMP: 

Message Meaning 

?IN ERR? A hardware error occurred while 

reading the input file and /G was 
not specified in the command line. 



?OUT ERR? 



A hardware error occurred while 
writing an output file, or the 
output device was full. 



?LP NOT FND? 



A line printer handler is not 
available on the system. 
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FILEX 



J.l FILEX OVERVIEW 

FILEX is a general file transfer program used to convert files among 
devices for various operating systems. Transfers may be initiated 
between any block-replaceable RT-11 directory-structured device and 
PDP-11 DOS/BATCH DECtape (as input or output) , DOS/BATCH disk (as 
input only) , RSTS DECtape (as input or output) , and DECsystem-10 
DECtape (as input only) . 

"Wild-card" names (the *.* construction explained in Chapter 4) are 
permitted. Magtape and cassette are not supported in any operation. 



J. 1.1 File Formats 

FILEX can transfer files created by three different operating 
systems— RT-11, DECsystem-10, and DOS/BATCH (PDP-11 Disk Operating 
System/BATCH) . Data formats that may be used in a transfer are 
ASCII, image, and packed image. Because the file structure and data 
formats for each system vary somewhat, switches are needed in the 
command line to indicate the file structures and the data formats 
involved in the transfer. These switches are defined in Section 
J. 2.1. Devices are assumed to be in RT-11 file structure unless 
either a /S or /T switch (for DOS/BATCH and RSTS or DECsystem-10 
respectively) is indicated. If both input and output devices are 
RT-11 format (or are not file-structured) , FILEX will operate like 
PIP. 



J. 2 CALLING AND USING FILEX 

FILEX is called from the RT-11 system device by typing: 

R FILEX 

in response to the dot printed by the Keyboard Monitor. An asterisk 
is printed when FILEX is loaded and ready to accept command string 
input . 
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Type CTRL C to halt FILEX at any time and return control to the 
monitor. To restart FILEX, type R FILEX or the REENTER command in 
response to the monitor's dot. 



J. 2.1 FILEX Switch Options 

Table J-l lists the switch options which are used for various FILEX 
operations. /S and /T must appear following the device and filename 
to which they apply; other switches may appear anywhere in the 
command line. These switches are explained in more detail following 
the table. 



Switch 



/A 



/D 
/F 
/I 



/L 



/P 



/S 



Table J-l 
FILEX Switch Options 



Meaning 



Indicates a character-by-character ASCII transfer in 
which rubouts and nulls are deleted; when /T is also 
used, each PDP-10 word is assumed to contain five 7-bit 
ASCII bytes. (The transfer terminates upon reaching a 
tZ for compatibility with RSTS; the tZ is not 
transferred.) 



Deletes the named file from the device; 
DOS/BATCH and RSTS DECtape. 



valid only for 



Causes a "fast" listing of the device directory by 
listing filenames only. 



Performs an image mode transfer; 
either DOS /BATCH, RSTS or 



transfer; 



if 



or 
the 



if the input is 
RT-11, this is a 
is from 



input 



word- f or-word 

DECsystem-10, /I indicates that the file resembles a 
file created on DECsystem-10 by MACY11, MACX11, or 
LNKX11 with the /I switch: in this case each 
DECsystem-10 36-bit word contains one PDP-11 8-bit byte 
in its low-order bits. 



Causes a complete listing of the device directory, 
including filenames, block lengths, and creation dates, 
to appear on the console terminal. 

Performs a packed image transfer; if the input is 
either DOS/BATCH, RSTS or RT-11, this is a 
word-for-word transfer; if the input is from 
DECsystem-10, /P indicates that the file resembles a 
file created on DECsystem-10 by MACY11, MACX11, or 
LNKX11 with the /P switch, in which case each 
DECsystem-10 36-bit word contains four PDP-11 8-bit 
bytes aligned on bits 0, 8, 18, and 26. This mode is 
assumed if no mode switch {/A, /I) is indicated in a 
command line. 

Indicates the device is a legal DOS/BATCH (or RSTS) 
block-replaceable device; the switch must appear on the 
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Switch 



A 

/v 
/z 



Table J-l (Cont) 
FILEX Switch Options 

Meaning 



same side of the command line as the device to which it 
applies. 

NOTE 

Neglecting to include the /S switch in a 
command line involving DOS/BATCH (or 

RSTS) causes unpredictable results. 

Indicates the device is a legal DECsystem-10 block- 
replaceable device; the switch must appear on the same 
side of the command line as the device to which it 
applies. 

Types out version number of FILEX. 

Zeroes the directory of the specified device in the 
proper format (valid only for DOS/BATCH and RSTS 
DECtape) . 



J. 2. 2 Transferring Files Between RT-11 and DOS/BATCH (or RSTS) 

File transfers may be initiated between block-replaceable devices used 
by RT-11 and the PDP-11 DOS/BATCH system. Input from DOS/BATCH may be 
either disk or DECtape; both linked and contiguous files are supported 
as input. If the input device is a DOS /BATCH disk, the user should 
specify a DOS/BATCH user identification code (called a UIC; refer to 
the DOS/BATCH Handbook , DEC-11-0DBHA-A-D) . This UIC then becomes 
default for all future transfers. If no UIC is specified, the current 
default UIC is used (see the description of UIC, following) . Output 
to DOS/BATCH is limited to DECtape only. DECtape used under the RSTS 
system is also legal as both input and output, since its format is 
identical to DOS/BATCH DECtape; see the PDP-11 Resource Sharing Time- 
Sharing System User's Guide , DEC-11-0RSUA-D-D. Any valid RT-11 file 
storage device may be used for either input or output in the transfer. 
The RT-11 device DK: is assumed if no device is indicated. 



NOTE 

An RT-11 DECtape can hold more 
information than a DOS/BATCH or RSTS 
DECtape. Thus, caution should be 
observed in copying files from a full 
RT-11 tape to a DOS DECtape as some 
information may not transfer. In such a 
case an error message will be printed 
and the transfer will not be completed. 

When a transfer from an RT-11 device to 
a DOS DECtape occurs, the block size of 
the file may increase. However, if the 
file is later transferred back to an 
RT-11 device, the block size does not 
decrease. 



To transfer a file from a legal DOS/BATCH block-replaceable device (or 
RSTS DECtape) to a legal RT-11 device, the command string format is: 
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*dev: f ilnam.ext=dev: f ilnam.ext/S/s [UIC] 



where: 



dev: 



filnam.ext 



/S 



/s 



[UIC] 



on the output side, any valid RT-11 device (if 
that device is not file-structured, filnam.ext may 
be omitted); on the input side, DOS/BATCH DECtape 
or disk, or RSTS DECtape. 

for output, any valid RT-11 filename and 
extension; for input, any valid DOS /BATCH 
(RSTS) filename and extension. 

the switch from Table J-l which designates a 
DOS/BATCH (RSTS) block-replaceable device. (This 
switch MUST be included in the command line.) 

optionally any other switch (one only) from Table 
J-l (in this case, /A is the only meaningful 
switch which could be chosen) ; /A indicates an 
ASCII transfer is to be performed in which nulls 
and rubouts are deleted; if /A is not used, the 
transfer will be performed word-for-word. 

the DOS/BATCH user identification code in the 
format [nnn,nnn] where nnn represents 1 to 3 octal 
digits less than or equal to 377 specifying first 
the user-group number, and then the individual 
user number; this code may be placed anywhere on 
the side of the command line containing the 
DOS/BATCH device; whenever a UIC is entered, it 
becomes the default for any further DOS/BATCH 
transfers; the initial default value is [1,1] . 



NOTE 

A UIC need not be indicated in any 
command line if accessing only DECtape 
since individual users do not "own" 
files on DECtape under DOS; no error 
will occur if a code is used, however. 



To transfer files from an RT-11 storage device to a DOS/BATCH or 
RSTS DECtape, the command line format is as follows: 

*DTn:filnam.ext/S/s=devt filnam.ext 



where : 

DTn: 



a valid DOS/BATCH (RSTS) DECtape assignment 
(only DECtape is legal for output) . 



filnam.ext = for output, any valid DOS/BATCH 
and extension; for input, 
filename and extension. 



(RSTS) filename 
any valid RT-11 



/S 



the switch from Table J-l which designates a 

DOS/BATCH (RSTS) block-replaceable device. (This 
switch MUST be included in the command line.) 
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/s = optionally any other switch (one only) from Table 

J-l (in this case, /A is the only meaningful 
switch which could be chosen) ; /A indicates an 
ASCII transfer is to be performed in which nulls 
and rubouts are deleted; if /A is not used, the 
transfer will be performed word-for-word. 

dev: = any valid RT-11 device. 

Examples : 

*DT2:S0RT. HBC/S=SORT. ABC 

This command instructs FILEX to transfer a file called SORT. ABC from 
the RT-11 system device to a DOS /BATCH (or RSTS) formatted DECtape 
on unit DT2. 

*PP :=DT2:TVPE. FIL/S/fl 

This command allows a file to be transferred from DOS/BATCH (or 
RSTS DECtape to the papertape punch under RT-11. The transfer is 
done in ASCII mode. 

*DK : *. * = RK1 : MFICR1. MfiC/SC 268, 206 3 

This command causes the file MACR1.MAC from the DOS /BATCH disk on unit 
1 which is stored under the UIC [200,200] to be transferred to the 
RT-11 device DK. [200,200] becomes the default UIC for any further 
DOS/BATCH operations. 



J. 2. 3 Transferring Files to RT-11 from DECsystem-10 

Files may be transferred to RT-11 devices from a DECsystem-10 DECtape 
whenever a foreground job is not running (this restriction is due to 
the fact that when reading DECsystem-10 files, FILEX accesses the 
DECtape control registers directly rather than using the RT-11 DECtape 
control handler) . Output may be to any valid RT-11 device; 
DECsystem-10 DECtape is the only valid input device. The format of 
the command line 1st 

*dev:filnam.ext=DTnsfilnam.ext/T/s 
where : 

dev: - any valid RT-11 device; if that device is not 
file-structured, the filnam.ext may be omitted. 

filnam.ext ■ for output, any valid RT-11 filename and 
extension; for input, any valid DECsystem-10 
filename and extension (see NOTE below) . 

°Tn: = a valid DECsystem-10 DECtape assignment (only 
DECtape is legal for input) . 

A " the switch from Table J-l which . signifies a 

DECsystem-10 DECtape. When using /T, especially | 
with /A, the time of day clock will lose time. It 
should be examined with the monitor TIME command, 
and reset if necessary. 
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/a «■ any other switch from Table J-l which specifies 

the mode of transfer. Only one additional switch 
may be indicated per transfer; /P is assumed if 
no other mode is specified. 



NOTE 

RT-11 files may be indirectly converted 
to DECsystem-10 format by running RT-11 
FILEX and converting the files to DOS 
formatted DECtape, and then running 
DECsystem-10 FILEX to read the DOS 
DECtape; however, it is currently not 
possible under RT-11 to convert files 
directly from RT-11 to DECsystem-10 
format . 



Examples : 



*DT2:STfiND. L I S = DT1 : STAND. LIS/T/fi 



The ASCII file STAND. LIS is converted from DECsystem-10 ASCII format 
to RT-11 ASCII format and stored under RT-11 on DECtape 2 as 
STAND. LIS. 

NOTE 

Transfers from DECsystem-10 DECtape to 
RT-11 DECtape may cause an <UNUSED> 
block to appear after the file on the 
RT-11 device. This is a result of the 
method by which RT-11 handles the 
increased amount of information on a 
DECsystem-10 DECtape. 

*SV:*. NEW=DT8:* LIS/T 

This command indicates that all files on DECsystem-10 DECtape with 
the extension .LIS are to be transferred to the RT-11 system device 
(disk or DECtape) using the same filename and an extension of .NEW. 
The /P switch is the assumed transfer mode. 



J. 2. 4 Listing Directories 

| Device directories of any of the block-replaceable devices used in a 
FILEX transfer can be listed on the console terminal. The following 
FILEX command lines are used: 

*dev:/L for RT-11 

*dev:/L/S for DOS /BATCH (RSTS-11) 

*DTn:/L/T for DECsystem-10 
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APPENDIX K 
SOURCE COMPARE (SRCCOM) 



The RT-11 Source Compare program (SRCCOM) is used to compare two ASCII 
files and to output any differences to a specified output device. It 
is particularly useful when the two files are different versions of a 
single program, in which case SRCCOM prints all the editing changes 
which transpired between the two versions. 



K.l CALLING AND USING SRCCOM 

To run SRCCOM type the command: 

R SRCCOM 

followed by a carriage return in response to the dot printed by the 
Keyboard Monitor; the CSI prints an asterisk. Then enter the names 
of the files which are to be compared using a command string in the 
following format: 

dev s output=dev : inputl , de v : input2/s 

where : 

dev: is any valid device specification. 

output is the filename and extension assigned to the output 
file. If no output file is indicated, output is 
directed to the terminal. 

inputl... are the input source filenames and extensions to be 
compared . 

/s is one of the switches listed in Table K-l. 

Source files are examined line by line for groups of lines which 
match. When a mismatch occurs, all differences are output until n 
successive lines in the first file are identical to n lines in the 
second file. The number (n) is a variable which the user can set with 
the /L switch. 
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K.l.l Extensions 



No default extension is assigned by SRCCOM to the output file. The 
default extension for an input file is .MAC, representing a source 
file in MACRO language. 



K.1.2 Switches 

Command switches are generally placed at the end of the command string 
but may follow any filename in the string. The following switches 
can appear in the command string: 

Table K-l 
SRCCOM Switches 



Switch 



Meaning 



/B 
/C 



/F 



/H 



/L:n 



/S 



Compare blank lines, 
lines are ignored. 



Without this switch, blank 



Ignore comments (all text on a line preceded by a 
semicolon) and spacing (spaces and tabs) . This 
switch does not cause a line consisting entirely 
of a comment to become a blank line, and therefore 
ignored in the line count. 

Include form feeds in the output file. (Form 
feeds are still compared if /F is not used, 
but they are not included in the output of 
differences.) 

Type list of switches available (help text) . No 
I/O device is necessary since /H always prints the 
help text on the terminal. 

Specify the number of lines that determines a match 
(n is an octal number <=310) . All differences 
occurring before and after a match are output. In 
addition, the first line of the current match is 
output after the differences to aid in locating 
the place within each file at which the 
differences occurred. The default value for n is 
3. 

Ignore spaces and tabs. 



K.2 OUTPUT FORMAT 

The first line of each file is always output as identification and is 
| also compared. A blank line is then printed, followed by the 
differences between the files, in the following format: 
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1) 1 FILEA 

1) A 
**** 

2)1 FILEB 

2) A 

********** 

% FILES ARE DIFFERENT 

The different lines are listed followed by a reference line which is 
the same for both files. Note the example below. 

The following example uses SRCCOM to compare an edited file and its 
backup version. The default value for a match is 3 lines. Blank 
lines are ignored but all other characters are compared. 

Following the example is a coded explanation of the comparison. 

. R SRCCOM 

*RK1 :LINK0. FB, LINKS. BRK 
A/ 1m .TITLE RTLINK ROOT CDC'E X02-16 

X 2:> 1 .TITLE RTLINK ROOT CODE X02-15 

SEVENK= 21452 -MINIMUM CORE TO STRRT LINKER 

. MCALL . CSISPC, . CSIGEN, . SETTOP, . LOCK, . UNLOCK 
SEVENR' = 21500 ;JU£T BELOW 8K RESIDENT 

. MCALL . CSISPC, . CSIGEN, . SETTOP, . LOCK, . UNLOCK 

. GLOBL RSWIT, RELPTR, FBTXT, OVLNUM, RELOVL, RL^TPT 
. GLOBL RELRDR, PNRELO, RELID1, RSI21, 0VSIZ1, OVLCDE 

. GLOBL RSWIT, RELPTR, FBTXT, OVLNUM, RELOVL 

. GLOBL RELRDR, PNRELO, RELID1, RSI21, 0VSIZ1, OVLCDE 

■ BLKW ; CURRENT REL ELK OVERLRV NUM 

■ BLKW ."POINTER TO CURRENT REL BLK LOCATION 

•BLKW /POINTER TO CURRENT REL BLK LOCATION 

.ASCII /RT-11 LINK X02-16/ 
.ASCII / LOAD MAP / 
*# ** 

B{ 2)2 MTITLE: .ASCII /RT-11 LINK X02-15/ 
C{ 2> . ASCII / LOAD MAP / 

f D12 . IF DF FB 

B< 1> MOV OBLK,RLSTRT ;IND START OF OVL FOR REL BLK 

V. 1) . ENDC 

C { 1> BR 1* 




■T I* 1* 1* 

C (2)12 BR 

0{ JiFILES ARE DIFFERENT 



1$ 
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A Headers, consisting of the first line of each file; for 
identification purposes. 

B n)m. A notation where n is the number of the input file, and 
m is the page number (less than 256 decimal) of the input file 
on which the text appears. The right column lists the lines in 
the files which are different. 

C Following a section of differences, a line identical to each file 
is output for reference purposes. 

D Indicates that the files are different (this is printed on the 
system console, not in the output file) . 

This example uses the /L:n switch and sets the number of lines that 
determines a match to 2 lines. The first two columns represent the 
input files: 



TEST FILE 
LINE C 
LINE E 
LINE C 
LINE D 
LINE F 
LINE H 
LINE I 
LINE J 



TEST FILE 2 
LINE C 
LINE D 
LINE C 
LINE E 
LINE F 
LINE G 
LINE H 
LINE I 
LINE J 

The files are compared and differences listed on the line printer. 

*LP:=TEST1, TE5T2/L:2 

iJt TEST FILE 1 
2Ji TfcST FILE 2 
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\)i 


LINE E 


l) 


LINE C 


13 


CINE 


1) 


LINE F 


1) 


LINE H 


**** 




2)1 


LINE D 


a) 


LINE C 


2) 


LINE E 


2) 


LINE F 


2) 


LINE 8 


2) 


LINE H 



********** 

This message prints on the terminal indicating that the files are 
different. 

XFILES ARE DIFFERENT 

K. 3 SRCCOM ERROR MESSAGES 

The following errors may be reported by SRCCOM: 



Messages 
?COR OVR? 

?IN ERR? 

?OUT ERR? 

7SWITCH ERROR? 

?TOO MUCH DIFFERENCE? 



Meaning 

Not enough memory to hold a particular 
difference section. 

A hardware error occurred in reading 
input . 

A hardware error occurred in writing 
output file, or output device full. 

An invalid switch was found or a switch 
other than /L was given a value. 

More than 310 (octal) lines of 
difference between two files were found. 
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PATCH 



The PATCH utility program is used to make code modifications to memory 
image (.SAV) files, including overlay-structured and monitor files. 
PATCH, like ODT, can be used to interrogate, and then to change, words 
or bytes in the file. 

PATCH provides eight relocation registers. Before changing a program 
with PATCH, copy the old file to a backup file with PIP, as the old 
file is modified when PATCH is used. 



L.l CALLING AND USING PATCH 

To run PATCH, type the command: 

R PATCH 

followed by the RETURN key in response to the dot printed by the 
monitor. PATCH prints a version number messages 

PATCH V01- 02 

and then prints the message: 

FILE NAME — 

In response to the asterisk, enter the name of the file to be 
modified, using the following format: 

dev : f ilnam. ext/M/O 
where : 

dev: represents an optional device specification; if 

not specified, DK: is assumed. 

f ilnam. ext represents the name of the file which is to be 
patched, if an extension is not indicated, .SAV is 
assumed . 

/M must be used if the file is an RT-11 monitor file. 

/O must be used if the file is an overlay-structured 

file. 
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After this information has been entered, the Command String 
Interpreter prints an asterisk indicating that it is ready to accept a 
command. Note that /0 and /M, if used, must be specified when the 
file name is typed} they are not legal at any other time. 



L.2 PATCH COMMANDS 

Table L-l summarizes the PATCH commands. 



Table L-l 
PATCH Commands 



Command 


Action 


Vr/nR 


Set relocation register n to value Vr. 


b;B 


Set bottom address of overlay file to b. 


[s:]r,o/ 


Open word location Vr + o in overlay 
segment s . 


[s:]r,o\ 


Open byte location Vr + o in overlay 
segment s . 


<CR> 


Close currently open word/byte. 


<LF> 


Close currently open word/byte and open 
the next one. 


t or 


Close currently open word/byte and open 
the previous one. 


@ 


Close the currently open word and open 
the word addressed by it. 


F 


Begin patching a new file. 


E 


Exit to RT-11 monitor. 



Explanations of each command follow. An example of the use of the 
commands is provided in Section L.3. 



L.2.1 Patch a New File 

The F command causes PATCH to close the file being patched, and accept 
a new file name to be patched. 
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L.2.2 Exit from PATCH 



The E command causes PATCH to close the file being patched and return 
control to the RT-11 monitor. 



L.2.3 Examine, Change Locations in the File 

For a non-overlay file, a word address may be opened, as with ODT, by 
typing : 

[< re location register>,] offset/ 

At this point, PATCH will type out the contents of the location and 
wait for the user to type in either new location contents (in octal) 
or another command. 

In an overlay file, the format is: 

Ksegment number>:] [< relocation register>,] offset/ 

Where < segment number > is the overlay segment number as it is printed 
on the link map for the file. If it is omitted, the root segment is 
assumed. 

Similarly, to open a byte address in file, the format is: 

[<relocation register >,] of fset\ 
for non-overlay files, or 

Ksegment number>:] [<relocation register>,]offset\ 
for overlay files. 

Once a location has been opened, the user may optionally type in the 
new contents in the format: 

[<relocation regis ter>, lvalue 

followed by one of these control characters: 

< carriage return> Close the current location by changing 

its contents to the new contents (if 
specified) , and await more control 
input. 

<line feed> Close the current location, and open the 

next word/byte. 

* or /s Close the current location, and open the 

previous word/byte. 

§ Close the current word location, and 

open the word addressed by it (in the 
same segment if an overlay file) . 
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L.2.4 Set Bottom Address 

To patch an overlay file, PATCH must know the bottom address at which 
the program was linked if it is different from the initial stack 
pointer. This is the case if the program sets location 42 in an 
.ASECT. To set the bottom address, type: 

<bottom address >;B 

Note that the B command must be issued before any locations are opened 
for modification. 



L.2.5 Set Relocation Registers 

The relocation registers 0-7 are set, as with ODT, by the R command. 
The R command has the format: 

Relocation value >; Relocation register >R 

Once one of the eight relocation registers has been set, the 
expression: 

Relocation register >,<octal number> 

typed as part of a command will have the value t 

Relocation value> + <octal number> 



L„3 EXAMPLES USING PATCH 

The following example shows how to patch a non-overlaid file. Assume 
the following program (EXAM) s 

.MAIN, RT-li MACRO VM02-08 PACE 1 

1 
2 

3 000019 CRi 19 

4 000013 IF* 12 

9 000000' tCSISCT MAIN 

8 tMCALL .PRINT, .EXIT 

7 ,NUST BEX 

8 0010000 124 MS6I .ASCII /THIS IS A SUCCESSFUL P ATCH/«C«>«LF> 

9 .LIST BEX 

10 00034 0004^3 START! BR EXIT 

11 00036 .PRINT #MSG 

12 00044 EXIT! .EXIT 

13 000034' .END START 

This program has been assembled with MACRO ana linked with LINK; 
execution causes no output of text: 

. R EXAM 
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To make a line of text print on the terminal, PATCH is used as 
follows : 

R PATCH 

PATCH V01-02 

FILE NRME-- 

*E!s'flM. SAV 

+1806; 0R 

*0, 34/ 403 240 

*E 



Now when the program is executed: 

R EXfiM 
THIS IS A SUCCESSFUL PflTCH 

The next example demonstrates a similar situation, only includes an 
overlay file. These programs have been assembled and linked; the 
output of both operations is included: 

.MAIN. KT-1 1 HACRU VMI32-08 3-3KP-74 PAGE l 

1 
2 

9 000013 CRR 15 

4 (900*13 LFf 12 

9 00000? PC* X7 

6 000000) .CSECT MAIN 

7 .BLQBL ENTRY, MSGl 

8 .MCALL .PRINT, .EXIT 

9 ■NIlIST BEX 

}? lll\i JSi M8h * ,miZ /THIS * 8 A SUCCESSFUL PATCH, « C R><LF> 

U 0*0Ji> 124 MSS1J .ASCIZ /THIS Is AN OVEKLAY PATCH/ 

12 .LIST SEX 

13 00066 000409 START! Bn E*Jt 

14 210070 .PRINT #M8G 

15 00076 004767 EXIT! JSR PC, ENTRY 

0000006 
18 0*1*8 .EXIT 

17 000066' ,BNi3 START 
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.(IAIN. RT«U MACRO VMB2-0B 3»$£P-74 PAGE I 



i 
2 

3 14001015 CR* 15 

4 000013 LM 12 

5 000007 PC" %7 

6 000000' .CSECT OVL 

7 ■MCALL, .PRINT 

8 .GIOBL MSG1 

9 .GLOttL ENTRY 

10 1)0000 000403 ENTKYI BR RETURN 

11 001302 .PRINT »flSGl 
U H0010 00«207 RETURNI »TS PC 

13 000001' .END 



RT-H LINK X03-18 LOAD MAP 

PTCm ,8AV 03-SEP-74 

SECTION ADUR Slife ENTrfY AOD» ENTRY ADOH ENTRY A0CR 

, ASS, 000000 001122 

MAIN 001122 000104 MSG1 001157 

OVERLAY Rfc&IUN 000001 SEGMENT 000001 

OVL 001230 000012 ENTRY 001230 

TRANSFER ADDRESS * 001210 
HIGH LIMIT • 001242 



Running the program (PTCH) produces no terminal output: 

. R PTCH 

But by using PATCH to modify the file as follows: 



L-6 



PATCH 



. R PATCH 

PRTCH VBi-02 

FILE NRME-- 
*PTCH. SRV/O 
*1230; 8R 
*1 : 0< 0/ 403 
*E 



240 



the following line results t 



R PTCH 
THIS IS AN OVERLRV PRTCH 



L.4 PATCH ERROR MESSAGES 

Error messages which may occur under PATCH follow. 



Message 
?ADDR NOT IN SEG? 

?BAD SWITCH? 
7BOTTOM ADDR WRONG? 



7INCORRECT PILE SPEC? 
7INSUFFICIENT CORE? 

? INVALID RELOC REG? 

7INVALID SEG NO? 
?MUST OPEN WORD? 

?MUST SPECIFY SEG? 



Meaning 

The address is 
overlay segment. 



not in the specified 



Typed a switch other than /O or /M. 

The bottom address specifed or contained 
in location 42 of an overlay file is 
incorrect. Specify the correct one 
using the b:B command. 



The response to 
message was not 
Try again. 



the "FILE NAME — " 
of the correct form. 



PATCH did not have enough memory to hold 
the file's device handler plus the 
internal "segment table." This message 
should not occur. 

Tried to reference a relocation register 
outside the range 0-7. 

The segment number St does not exist. 

The @ command was typed when a byte 
location was open. 

The address referenced is not in the 
root section; a segment number St must 
be used. 
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?N0 ADDR OPEN? 

?NOT IN PROGR BOUNDS? 

?ODD ADDRESS? 

?ODD BOTTOM ADDR? 

?PROG HAS NO SEGS? 

?READ ERROR? 
?WRITE ERROR? 



The <line feed>, t or 9 command was 
typed when no location was open. 

Tried to open a location beyond the end 
of the file. 

Tried to open a word address which was 
odd. (Use "\".) 

The bottom address specified or 
contained in location 42 of an overlay 
file is odd. 

The file specified as an overlay file is 
not. 

File I/O error in reading. 

File I/O error in writing. 
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The RT-11 PATCHO program is used to correct and update object modules 
(files output by the assemblers or by the FORTRAN compiler) . It is 
particularly useful when making corrections to routines that are in 
.OBJ format for which the source files are not available. PATCHO 
cannot be used to patch libraries built by LIBR, but it can be used to 
patch the OBJ modules from which a library is built. 



M.l CALLING AND USING PATCHO 
To run PATCHO type the command: 
R PATCHO 



in response to the dot printed by the Keyboard Monitor. When PATCHO 
«m * Gad * to accept commands, an asterisk is printed. The standard 
RT-11 command string is not used for PATCHO. Specific commands 
{ described in Section M.2) are typed in response to the asterisk. 

Type CTRL C to halt PATCHO at any time and return control to the 
monitor. To restart PATCHO, type R PATCHO or the REENTER command in 
response to the monitor's dot. 



M.2 PATCHO COMMANDS 

There are nine commands and arguments accepted by PATCHO. All 
arguments to a command must be separated from the command name by one 
or more spaces (e.g., POINT TOP is acceptable, POINTTOP is not). 
Commands are terminated by a carriage return. 



M.2.1 OPEN Command 

The OPEN command sets input and output file names. When the command 
is given, PATCHO prints: 

ENTER INPUT PILE* 
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on the console terminal, and waits for a standard RT-11 device and 
file specification to be entered (devrfilnam.ext) . After the input 
specification is given, followed by a carriage return, PATCHO responds 
with: 

ENTER OUTPUT FILE* 

A device and file specification (followed by a carriage return) for 
the desired output file is now accepted from the console. 

NOTE 

There is no default extension. 
Therefore, the user must explicitly 
specify the filename and extension. 

Example : 

*OPEN 

E N T E R I N P 1.1 T F 1 I... E * R K 1 JOTS. B J 

E N T E R 1 J T P U T F 1 1... E * R K J. ! N E U) T S . B J 



M.2.2 POINT Command 

The POINT command locates an object module of a given name (used with 
concatenated object modules) and prepares it for subsequent WORD, 
BYTE, or DUMP operations. POINT takes one argument — the module name 
to be located. 

Example: 

♦POINT Gil NIT 



M.2.3 WORD Command 

The WORD command modifies a given word in an object module. There may 
be several arguments to the command, entered as illustrated below (the 
BYTE command is also included since its arguments are exactly the 
same; refer to Section M.2.4) : 



Address Specifier Value Specifier 



f WORD A CSECT + OFFSET = fflNAME OF f+\ 
\ BYTE J NAME < % >CSECT OR ( - ( 

^ J l. J GLOBAL SYMBOL^ J 



OFFSET 



where in the Address Specifier: 

1. CSECT is the name of the CSECT which contains the word to be 
modified. The CSECT must be present in the current module 
(the one specified in the POINT command) . 
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The CSECT NAME is optional; if omitted, the blank CSECT 
is assumed. To represent a CSECT name which contains 
embedded blanks ( . ABS . ) , a backarrow (SHIFT O) or underscore 
character should be used in place of each embedded blank. 

2. OFFSET is the octal location within the CSECT that is to be 
modified. OFFSET must be present. 

3. o is a delimiter and must be present. 
In the Value Specifier: 

1. If # is used, the absolute value of the OFFSET in the Value 
Specifier field is placed in the target location (the address 
indicated by the Address Specifier) . 

For example: 

♦ WORD PRO 6+ 2 4 ™# 4 

This command patches location 24 in CSECT PROG to contain the 
value 4. 

2. If % is used, displaced relocation is generated on the Value 
Specifier. This mode is used for PC-relative references. 
For example: 

♦ WORD P R G + 2 4 ^ % P R G 1 + 2 4 
This command patches PROG+24 to contain the value: 

Address (PR0G1+2 4) -Address (PROG+26) 

3." If neither # or % are specified, the address of the Value 
Specifier is placed in the target location. For example: 

*WGRD PR0G+24=PROG+±4 

This causes the word at PROG+24 to contain the address of the 
word at PROG+14, while: 

♦ WORD P R (3 + 2 4 =■■ S Y M if 1... + 

causes the word at PROG+24 to contain the address of the 
global symbol "SYMBOL". 

4. GLOBAL is optional and is the name of a global symbol whose 
value (address) is to be used in the word to be modified. 

5. The characters + or - are optional and indicate the siqn of 
the following OFFSET. If a global symbol is indicated, a + 
(or -) and OFFSET must be present. 



M.2.4 BYTE Command 

The BYTE command modifies a given byte in an object module. The 
arguments are the same as for WORD, explained in Section M.2.3. 
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Example : 



*BY1 



csec:ta*-2:i.^#:i.o:i. 



The byte in CSECTA whose offset is 21 is patched to contain octal 101 
(ASCII W A"). 



M.2.5 DUMP Command 

The DUMP command prints the contents of the object module currently 
being pointed to and causes an automatic POINT to the next module in 
the input file, if any. Use the monitor SET LP CR command first for 
correct output format. 



NOTE 

LIST and DUMP go to LPs (lineprinter) 
by default. If the user wants LIST and 
DUMP to go to the terminal, he must 
execute an ASSIGN TT:6 command before 
typing R PATCHO. 

Refer to Section M.4 for an example of the DUMP command. 



M. 2.6 LIST Command 

The LIST command lists the names of all the object modules in the 
input file in the order in which they appear in the file. A POINT 
command should be given after the LIST command to assure that 
PATCHO is positioned at the desired module for the next operation. 
LIST lists the names of all object modules in a file without changing 
the module being pointed to. 

Refer to Section M.4 for an example of the LIST command. 



M.2.7 EXIT Command 

The EXIT command returns to the operating system terminating a patch 
session and closing a file. The EXIT command takes no argument. As 
the EXIT command is executed, ENTER CHECKSUM:- - - is displayed. The 

user should type a six-digit octal number corresponding to the 
appropriate checksum for the patch (if any). If the checksum agrees, 
PATCHO prints STOP — and returns control to the monitor. If the 
checksum does not agree/ PATCHO prints PAUSE — ?BAD PATCH? and waits 
for user input. The user has two options: typing a CTRL C at this 
point aborts PATCHO without closing the output file, thus allowing 
PATCHO to be rerun and the patch to be reentered. For example: 



*E*IT 

ENTER CHECKSUM; 115570 



PAUSE 

"C 



?6fiD PATCH? 
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Typing a carriage return causes the output file to be closed, despite 
the bad patch, and returns control to the monitor. Note that in the 
latter case, if the output and input files were called by the same 
name and extension, the input file is destroyed and the output file 
contains an incorrect patch. 



M.2.8 DEC Command 

The DEC command is used generally by maintainers when creating system 
patches and when the proper checksum for the patch being made is 
unknown. If a DEC command is issued during a patch session, the EXIT 
command is automatically modified to display: 

ENTER CHECKSUM: 

followed by the correct checksum for the patch just completed. The 
checksum computed by PATCHO is derived from all of the commands 
entered during the session, thereby providing a safeguard against 
typographical errors. If the DEC command is used, it is the first 
command given. 

*DEC 



*EXIT 

ENTER CHECKSUM: 115576 

STOP -- 



M.2.9 HELP Command 

The HELP command prints an explanation of PATCHO commands. The HELP 
command takes no arguments. 



M.3 PATCHO LIMITATIONS 

Note the following limitations on the use of PATCHO: 

1. PATCHO only works with object modules or concatenated object 
modules, not with libraries. 

2. PATCHO always copies its input file to its output file as it 
makes changes. 

3. As a consequence of 2 (above) the POINT command can only be 
used to point to modules that physically follow the current 
module in the input file. 

4. If changes are being made to a file, PATCHO must be given an 
EXIT command when all the changes are complete in order to 
assure that the entire input is copied to the output (i.e., 
CTRL C should not be used) . 

5. The LIST and DUMP commands will work in an 8K system only 
if an ASSIGN TT:6 command has been entered prior to running 
PATCHO. Otherwise 12K is required for these two commands. 
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M.4 EXAMPLES 

The following is an example of the PATCHO command LIST in which a few 
of the names of object modules in the library file (OTS.OBJ) are 
listed: 

*l:i:st 

OBJECT M0DULE8I 

ERRSS 

IVEC 

IVECP 

IPVEC 

FVEC 

FVECP 
PPVgC 

ovec 

OVEC^ 

DPVEC 

LVEC 

LVECf 

IPVEC 

ERRS 
ADTS 
OTINIT 

The next example is a sample of output produced by the PATCHO DUMP 
Command. The module is dumped by formatted binary block. 

*MJMP 

OUMP OP MODULE UP50 



BLOCK TYPE G8D 










GLOBAL USAGE 


DEFINED 


RELOC 


EXTERNAL 


SIZE/ADRS 


LPS0 MOD NAME 


NO 


NO 


NO 





. ABS, CSECT 


YES 


NO 


NO 





ERRARG GLOBAL 


NO 


NO 


YES 





ERRPDL GLOBAL 


NO 


NO 


YES 





ERRSYN GLOBAL 


NO 


NO 


YES 





BLOCK TYPE GSD 










GLOBAL USAGE 


DEFINED 


RELOC 


EXTERNAL 


SIZE/ADRS 


EVAL GLOBAL 


NO 


NO 


YES 






BLOCK TYPE GSD 

GLOBAL USAGE DEFINED RELOC EXTERNAL SIZE/ADRS 

USE GLOBAL YES YES YES 104 

, ABS, TRAN ADR YES NO NO 1 

BLOCK TYPE GSD END 



BLOCK TYPE RLD 

ADDRESS RLD TYPE GLOBAL OFFSET 



1772 LCTR DEF 
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BLOCK TYPE 


TXT 








ADDRESS 


CONTENTS 
























2 















H 















6 















10 















12 















• 

• 

1476 




12602 


202 


25 




1500 




12600 


200 


25 




1502 




207 


207 






BLOCK TYPE MOD END 



M.5 PATCHO ERROR MESSAGES 
Message 

?BAD CHECKSUM? 

?BAD OBJ? 
?DUMP ERROR? 



7ILLEGAL COMMAND? 



7MODULE NOT FOUND? 



7MORE THAN 15 CHANGES? 



Explanation 

A formatted binary block in the input 
file has a checksum which does not agree 
with that calculated for its contents. 

The input file contains information 
which cannot be interpreted as an object 
module . 



An input/output 
dumping a module. 



error occurred while 



A command line was not recognized, or it 
was not in the proper format for the 

particular operation. 

The module requested in a POINT command 
was not found in the input file between 
the position of the file at the time of 

the POINT and the file's end. 

Too many changes have, been specified for 
a particular module. The patch should 
be broken up into several steps. 



?MORE THAN 5 CSECTS REQUIRE CHANGE? 

An attempt has been made to patch 
locations in too many different CSECTS. 
The patch should be made in several 
steps. 



?NO FILE OPEN? 



70FFSET? 



An attempt was made to 
other than "DEC" or ' 
OPEN command was issued. 



use a command 
•HELP" before an 



The offset supplied in a WORD or BYTE 
command is not an octal number, or is in 
improper format. 
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Message 
POUTPUT ERROR? 

?OUTPUT FILE TOO SMALL? 



PAUSE — ?BAD PATCH? 



Explanation 

A hardware error (or possibly a 
write-lock condition) occurred while 
attempting to write the output file. 

The space allocated to the output file 
is too small. This may be corrected by 
compressing the device with PIP (if 
enough total space is free on the 
device) , or by using another device for 
output. 

The checksum entered on exit does not 
agree with that calculated by PATCHO. 



M.5.1 Run-Time Error Messages 

Because PATCHO is a FORTRAN program, run-time error messages may occur. 
To find a complete explanation of each run- time error refer to the RT-11/ 
RSTS/E FORTRAN IV User's Guide or the RT-11 System Message Manual . 
Listed below are four of the most important run-time error messages which 
may be encountered. 



23 



28 



29 



30 



FATAL 



FATAL 



FATAL 



FATAL 



HARDWARE I/O ERROR 

A hardware error has been detected during 

operation. 



an I/O 



OPEN FAILED FOR FILE 

A file could not be found, there was no room in 
the device, or FORTRAN selected a channel already 
in use. 



NO ROOM FOR DEVICE HANDLER 

There is not enough free memory 

accommodate a specific device handler. 



left 



NO ROOM FOR BUFFERS 

There is not enough free memory 

required I/O buffers. 



left to set 



to 



up 
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APPENDIX N 
DISPLAY FILE HANDLER 

This appendix describes the assembly language graphics support 
provided under RT-11 for the GT40, GT44, and DECLab-11 display 
hardware systems. 

The following manuals are suggested for additional reference: 

For GT40 users: 

1. GT40 User's Guide (DEC-11-HGTGA-A-D) 

For GT44 users: 

1. GT44 User's Guide (DEC-11-HGT44-A-D) 

For DECLab-11 users: 

1. VTll Graphics Display Processor Manual (DEC-11-HVGTA-A-D) 

2. RT-11 BASIC Reference Manual (DEC-11-LBACA-B-D) 

N.l DESCRIPTION 

The GT40, GT44, and DECLab-11 have hardware configurations that 
include a display processor and CRT (cathode ray tube) display. The 
GT44 has a 17-inch tube; the GT40 and DECLab-11 use a 12-inch tube. 
Both systems are equipped with light pens and hardware character and 
vector generators, and are capable of high-quality graphics. The 
Display File Handler supports this graphics hardware at the assembly 
language level under the RT-11 monitor. 

N.l.l Assembly Language Display Support 

The Display File Handler is not an RT-11 device handler, since it does 
not use the I/O structure of the RT-11 monitor. For example, it is 
not possible to use PIP to transfer a text file to the display via the 
Display File Handler. Rather, the Display File Handler provides the 
graphics programmer the means for the display of graphics files and 
the easy management of the display processor. Included in its 
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capabilities are such services as interrupt handling, light pen 
support, tracking object, and starting and stopping of the display 
processor. 

The Display File Handler manages the display processor by means of a. 
base segment (called VTBASE) which contains interrupt handlers, an 
internal display file and some pointers and flags. The display 
processor cycles through the internal display file; any user graphics 
files to be displayed are accessed via display subroutine calls from 
the Handler's display file. In this way, the Display File Handler 
exerts control over the display processor, relieving the assembly 
language user of the task. 

Through the Display File Handler, the programmer can insert and remove 
calls to display files from the Handler's internal display file. Up 
to two user files may be inserted at one time, and that number may be 
increased by re-assembling the Handler. Any user file inserted for 
display may be blanked (the subroutine call to it bypassed) and 
unblanked by macro calls to the Display File Handler. 

Since the Handler treats all user display files as graphics 
subroutines to its internal display file, a display processor 
subroutine call is required. This is implemented with software, using 
the display stop instruction, and is available for user programs. 
This instruction and several other extended instructions implemented 
with the display stop instruction are described in Section N.3. 

The facilities of the Display File Handler are accessed through a 
library of macros (VTMAC) which generate calls to a set of subroutines 
in VTLIB. VTMAC is the MACRO library, and its call protocol is 
similar to that of the RT-11 macros. The expansion of the macros is 
shown in Section N.6. VTMAC also contains, for convenience in 
programming, the set of recommended display processor instruction 
mnemonics and their values. The mnemonics are listed in Section N.7 
and are used in the examples throughout this appendix. 

VTCAL1 through VTCAL4 are the set of subroutines which service the 
VTMAC calls. They include functions for display file and display 
processor management. These are described in detail in Section N.2. 
VTCALl through VTCAL4 are currently constructed, along with the base 
segment VTBASE, as a library of (five) modules, called VTLIB. 



N.1.2 Monitor Display Support 

The RT-11 monitor, under Version 2, directly supports the display as 
console device. A keyboard monitor command, GT ON (GT OFF) described 
in Section 2.7.1, permits the selection of the display as console 
device. Selection results in the allocation of approximately 1.25k 
words of memory for text, buffer and code. The buffer holds 
approximately 2000 characters. 

The text display includes a blinking cursor to indicate the position 
in the text where a character is added. The cursor initially appears 
at the top left corner of the text area. As .lines are added to the 
text the cursor moves down the screen. When the maximum number of 
lines are on the screen, the top line is deleted from the text buffer 
when the line feed terminating a new line is received. This causes 
the appearance of "scrolling", as the text disappears off the top of 
the display. 
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When the maximum number of characters have been inserted in the text 
buffer, the scroller logic deletes a line from the top of the screen 
to make room for additional characters. Text may appear to move 
(scroll) off the top of the screen while the cursor is in the middle 
of a line. 

The Display File Handler can operate simultaneously with the scroller 
program, permitting graphic displays and monitor dialogue to appear on 
the screen at the same time. It does this by inserting its internal 

display file into the display processor loop through the text buffer. 
However, the following should be noted. Under the Single-Job Monitor, 
if a program using the display for graphics is running with the 
scroller in use (that is, GT ON is in effect) , and the program does a 
soft exit (.EXIT with RO not equal to 0) with the display stopped, 
the display remains stopped until a CTRL C is typed at the keyboard. 

This can be recognized by failure of the monitor to echo on the screen 
when expected. If the scroller text display disappears after a pro- 
gram exit, always type CTRL C to restore. If CTRL C fails to restore 
the display, the running program probably has an error. 

Four scroller control characters provide the user with the capability 
of halting the scroller, advancing the scrolling in page sections, 
and printing hard copy from the scroller. These are described in 
Chapter 2. 

NOTE 

The scroller logic does not limit the 
length of a line, but the length of text 
lines affects the number of lines which 
may be displayed, since the text buffer 
is finite. As text lines become longer, 
the scroller logic may delete extra 
lines to make room for new text, 
temporarily decreasing the number of 
lines displayed. 



N.2 DESCRIPTION OF GRAPHICS MACROS 

The facilities of the Display File Handler are accessed through a set 
of macros, contained in VTMAC, which generate assembly language calls 
to the Handler at assembly time. The calls take the form of 
subroutine calls to the subroutines in VTLIB. Arguments are passed to 
the subroutines through register and, in the case of the .TRACK 
call, through both register and the stack. 

This call convention is similar to Version 1 RT-11 I/O macro calls, 
except that the subroutine call instruction is used instead of the EMT 
instruction. If a macro requires an argument but none is specified, 
it is assumed that the address of the argument has already been placed 
in register 0. The programmer should not assume that RO is preserved 
through the call. 

N.2.1 .BLANK 

The .BLANK request temporarily blanks the user display file specified 
in the request. It does this by by-passing the call to the user 
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display file, which prevents the display processor from cycling 
through the user file, effectively blanking it. This effect can later 
be cancelled by the .RESTR request, which restores the user file. 
When the call returns, the user is assured the display processor is 
not in the file that was blanked. 

Macro Call: .BLANK .faddr 



where: .faddr is the address of the user 

display file to be blanked. 



Errors : 

No error is returned. If the file specified was not found in 
Handler file or has already been blanked, the request is ignored. 



the 



N.2.2 .CLEAR 

The .CLEAR request initializes the Display File Handler, clearing out 
any calls to user display files and resetting all of the internal 
flags and pointers. 

After initialization with .LNKRT (Section N.2.4), the .CLEAR request 
can be used any time in a program to clear the display and to reset 
pointers. All calls to user files are deleted and all pointers to 
status buffers are reset. They must be re-inserted if they are to be 
used again. 

Macro Call: .CLEAR 

Errors : 

None. 

Example : 

This example uses a .CLEAR request to initialize the Handler, then 
later uses the .CLEAR to re-initialize the display. The first .CLEAR 
is used for the case when a program may be restarted after a CTRL C or 
other exit. 



EX 1 1 

RSTRTl 



ill 



BR 
BIS 

•UNLNK 

•LNKRT 

•CLEAR 

•INSRT 

•TTYIN 

CMP8 

8NE 

•CLEAR 

•IN8RT 



R5TRT 

• 280.(9 «U»i«« 



•FILE1 



• 12, R0 
IS 

•FILE2 



r BET RENTER BIT IN J3W 

(CLEARS LINK FLAG FOR RESTART 

ISET UP VECTORS, START DISPLAY 

UNITIALIZE HANDLER. 

(DISPLAY A PICTURE 

(WAIT FOR A KEY STRIKE 

(LINE FEED? 

(NO, LOOP 

(YES, CLEAR DISPLAY 

(DISPLAY NEW PICTURE 



FILE1I 



POINT 



500 

LONSV 

5031 INTX 



ORET 





(AT POINT £0,500) 



(DRAW A LJNE 
(TO (500,500) 



January 197 6 
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PlUai POINT »AT POINT (500,0) 

500 

10NGV IDRAW A tINI 

01INTX >T0 (500,300) 

500 

DRET 



.END f XI 

N.2.3 .INSRT 

The .INSRT request inserts a call to the user display file specified 
in the request into the Display File Handler's internal display file. 
.INSRT causes the display processor to cycle through the user file as 
a subroutine to the internal file. The handler permits two user files 
at one time. The call inserted in the handler looks like the 
following: 

DJSR ; DISPLAY SUBROUTINE 
.+4 ; RETURN ADDRESS 
.faddr ; SUBROUTINE ADDRESS 

The call to the user file is removed by replacing its address with the 
address of a null display file. The user file is blanked by replacing 
the DJSR with a DJMP instruction, bypassing the user file. 

Macro Call: .INSRT .faddr 

where: .faddr is the address of the user 

display file to be inserted. 

Errors : 

The .INSRT request returns with the C bit set if there was an error in 
processing the request. An error occurs only when the Handler's 
display file is full and cannot accept another file. If the user file 
specified exists, the request is not processed. Two display files 
with the same starting address cannot be inserted. 

Example : 

See the examples in Sections N.2.2 and N.2.4. 



N.2.4 .LNKRT 

The .LNKRT request sets up the display interrupt vectors and possibly 
links the Display File Handler to the scroll text buffer in the RT-11 
monitor. It must be the first call to the Handler, and is used 
whether or not the RT-11 monitor is using the display for console 
output (i.e., the KMON command GT ON has been entered). 

The .LNKRT request used with the Version 2 RT-11 monitor enables a 
display application program to determine the environment in which it 
is operating. Error codes are provided for the situations where there 
is no display hardware present on the system or the display hardware 
is already being used by another task (e.g., a foreground job in the 
Foreground/Background version) . 
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The existence of the monitor scroller and the size of the Handler's 
subpicture stack are also returned to the caller. If a previous call 
to .LNKRT was made without a subsequent .UNLNK, the .LNKRT call is 
ignored and an error code is returned. 

Macro Call: .LNKRT 

Errors : 

Error codes are returned in RO, with the N condition bit set. 

Code Meaning 



-1 



-2 



-3 



No VT11 display hardware is 
present on this system. 

VT11 hardware is presently 
in use. 

Handler has already been 
linked. 



On completion of a successful .LNKRT request, RO will contain the 
display subroutine stack size, indicating the depth to which display 
subroutines may be nested. The N bit will be zero. 

If the RT-11 monitor scroll text buffer was not in memory at the time 
of the .LNKRT, the C bit will be returned set. The KMON commands 
GT ON and GT OFF cannot be issued while a task is using the display. 

Example : 



STARTl 



CONTI 
iSl 



9BUFI 



FILEll 



.LNKRT 
SMI 

acs 

.SCROL 

.INSRT 

.TTYIN 

CM*B 

8NE 

.UNLNK 

.EXIT 

.BTTE 
.BYTE 
.WORD 

POINT 

see 

500 

ChAR 

.ASCII 

.EVEN 

ORET 

£1 



ERROR 
CONT 
«9BUF 
#FILE1 

#12, R0 
IS 



(LINK TO MONITOR 

(ERROR DOING LINK 

(NO SCROLL IP C SET 

(ADJUST SCROLL PARAMETERS 

(DISPLAY A PICTURE 

(WAIT FOR KEY STRIKE 

(LINE FEED? 

(NO, LOOP 

(YES, UNLINK AND EXIT 



/THIS IS FILEi. 



(LINE COUNT OF 5 
(INTEN5ITY TtSCALE OF 
(POSITION OF TOP LINE 

(AT POINT £500.500) 



(DISPLAY SOME TEXT 
TYPE CR TO EXIT/ 



1-8) 



ERROR! Error routine 



N-6 



Display File Handler 

N.2.5 .LPEN 

The .LPEN request transfers the address of a light pen status data 
buffer to VTBASE. Once the buffer pointer has been passed to the 
Handler, the light pen interrupt handler in VTBASE will transfer 
display processor status data to the buffer, depending on the state of 
the buffer flag. 

The buffer must have seven contiguous words of storage. The first 
word is the buffer flag, and it is initially cleared (set to zero) by 
the .LPEN request. When a light pen interrupt occurs, the interrupt 
handler transfers status data to the buffer and then sets the buffer 
flag non-zero. The program can loop on the buffer flag when waiting 
for a light pen hit (although doing this will tie up the processor, 
and in a Foreground/Background environment, timed waits would be more 
desirable) . No further data transfers take place, despite the 
occurrence of numerous light pen interrupts, until the buffer flag is 
again cleared to zero. This permits the program to process the data 
before it is destroyed by another interrupt. 

The buffer structure looks like this: 

Buffer Flag 

Name 

Subpicture Tag 

Display Program Counter (DPC) 

Display Status Register (DSR) 

X Status Register (XSR) 

Y Status Register (YSR) 

The Name value is the contents of the software Name Register 
(described in N.3.5) at the time of interrupt. The Tag value is the 
tag of the subpicture being displayed at the time of interrupt. The 
last four data items are the contents of the display processor status 
registers at the time of interrupt. They are described in detail in 
Table N-l. 



Macro Calls .LPEN .baddr 
where t .baddr 

Errors i 



is the address of the 7-word 
light pen status data buffer. 



None. 

If a .LPEN was already issued and a buffer specified, the new buffer 
address replaces the previous buffer address. Only one light pen 
buffer can be in use at a time. 



Example : 



LOOPl 



.INSRT «LPILE 

.LPEN #LBUF 

TST LBUF 

BEO LOOP 



t PROCESS DATA IN LBUP HERE, 
CLR LBUF 



BR 



LOOP 



IDISPLAY LPILE 
I3ET UP LPEN BUFFER 
ITEST LBUF FLAG, WHICH 
IWILL BE SET NON-ZERO 
ION LIGHT PEN HIT. 

fCLEAR THE BUFFER FLAG, 
/PERMITTING ANOTHER "HIT 1 ', 
IGO WAIT FOR IT, 
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LBUM 
IFILEl 



.BLKW 



I5IVEN *ORD IPEN BUFFER 



Table N-l 
Description of Display Status Words 



Bits 



Significance 



DISPLAY PROGRAM COUNTER (DPC=>172000) 



0-15 



Address of display processor 
program counter at time of 
interrupt. 



DISPLAY STATUS REGISTER (DSR= 172002) 



0-1 

2 

3 

4 

5 

6 

7 

8-10 

11-14 

15 



Line Type 

Spare 

Blink 

Italics 

Edge Indicator 

Shift Out 

Light Pen Flag 

Intensity 

Mode 

Stop Flag 



X STATUS REGISTER (XSR=172004) 



0-9 
10-15 



X Position 
Graphplot Increment 



Y STATUS REGISTER (YSR=172006) 



0-9 
10-15 



Y Position 
Character Register 
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N.2.6 .NAME 

The .NAME request has been added to the Version 2 Handler. The 
contents of the name register are now stacked when a subpicture call 
is made. When a light pen interrupt occurs, the contents of the name 
register stack may be recovered if the user program has supplied the 
address of a buffer through the .NAME request. 

The buffer must have a size equal to the stack depth (default is 10) 
plus one word for the flag. When the .NAME request is entered, the 
address of the buffer is passed to the Handler and the first word (the 
flag word) is cleared. When a light pen hit occurs, the stack's 
contents are transferred and the flag is set non-zero. 

Macro Call: .NAME .baddr 

where: .baddr is the address of the name register 

buffer. 

Errors : 

None. 

If a .NAME request has been previously issued, the new buffer address 
replaces the previous buffer address. 



N.2.7 .REMOV 

The .REMOV request removes the call to a user display file previously 
inserted in the handler's display file by the .INSRT request. All 
reference to the user file is removed, unlike the .BLANK request, 
which merely bypasses the call while leaving it intact. 

Macro Call: .REMOV .faddr 

where: .faddr is the address of the display file to be 

removed. 

Errors : 

No errors are returned. If the file address given cannot be found, 
the request is ignored. 



N.2.8 .RESTR 

The .RESTR request restores to view a user display file that was 
previously blanked by a .BLANK request. It removes the by-pass of the 
call to the user file, so that the display processor once again cycles 
through the user file. 

Macro Call: .RESTR .faddr 

where: .faddr is the address of the user file that is 

to be restored to view. 

Errors : 

No errors are returned. If the file specified cannot be found, the 
request is ignored. 
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N.2.9 .SCROL 

This request is used to modify the appearance of the Display Monitor's 
text display. The .SCROL request permits the programmer to change the 
maximum line count, intensity and the position of the top line of text 
of the scroller. The request passes the address of a two-word buffer 
which contains the parameter specifications. The first byte is the 
line count, the second byte is the intensity, and the second word is 
the Y position. Both line count and Y position must be octal numbers. 
The intensity may be a number from 1 to 8, ranging from lowest to 
highest intensity. If an intensity of 1 is specified, the scroller 
text will be almost unnoticeable at a BRIGHTNESS knob setting less 
than one-half. The scroller parameter change is temporary, since an 
.UNLNK or CTRL C restores the previous values. 

Macro Call: .SCROL .baddr 



where ; 



•baddr 



is the address of the two-word 
scroll parameters buffer. 



Errors: 

No errors are returned. No checking is done on the values of the 
parameters. A zero argument is interpreted to mean that the parameter 
value is not to be changed. A negative argument causes the default 
parameter value to be restored. 



Example: 



.9CR0L #SCBUP 



(ADJUST SCOLl PARAMETERS 



SCBUFI 



.BYTE 
.BYTE 
.ftORD 



5 

300 



/DECREASE # LINES TO 5, 
/LEAVE INTENSITY UNCHANGED, 
ITQP LINE AT Y « 300. 



N.2.10 .START 

The .START request starts the display processor if it was stopped by a 
.STOP directive. If the display processor is running, it is stopped 
first, then restarted. In either case, the subpicture stack is 
cleared and the display processor is started at the top of the 
handler's internal display file. 

Macro Call: .START 

Errors : 

None. 



N.2.11 .STAT 

The .STAT request transfers the address of a seven-word status buffer 
to the display stop interrupt routine in VTBASE. Once the transfer 
has been made, display processor status data is transferred to the 
buffer by the display stop interrupt routine in VTBASE whenever a 
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.DSTAT or .DHALT instruction is encountered (see Sections N.3.3 and 
N.3.4). The transfer is made only when the buffer flag is clear 
(zero). After the transfer is made, the buffer flag is set non-zero 
and the .DSTAT or .DHALT instruction is replaced by a .DNOP (Display 
NOP) instruction. 

The status buffer must be a seven-word, contiguous block of memory. 
Its contents are the same as the light pen status buffer. For a 
detailed description of the buffer and an explanation of the status 
words, see section N.2.5 and Table N-l. 

Macro Call: .STAT .baddr 

where: .baddr is the address of the status 

buffer receiving the data. 

Errors : 

No errors are indicated. If a buffer was previously set up, the new 
buffer address is replaced as the old buffer address. 



N.2.12 .STOP 

The .STOP request "stops" the display processor. It actually effects 
a stop by preventing the DPU from cycling through any user display 
files. It is useful for stopping the display during modification of a 
display file, a risky task when the display processor is running. 
However, a .BLANK could be equally useful for this purpose, since the 
.BLANK request does not return until the display processor has been 
removed from the user display file being blanked. 

Macro Call: .STOP 

Errors : 

None. 



NOTE 

Since the display processor must cycle 
through the text buffer in the Display 
Monitor in order for console output to 
be processed, the text buffer remains 
visible after a .STOP request is 
processed, but all user files disappear. 



N.2.13 .SYNC/. NOSYN 

The .SYNC and .NOSYN requests provide program access to the power line 
synchronization feature of the display processor. The .SYNC request 
enables synchronization and the .NOSYN request disables it (the 
default case) . 

Synchronization is achieved by stopping the display and restarting it 
when the power line frequency reaches a trigger point, e.g., a peak or 
zero-crossing. Synchronization has the effect of fixing the display 
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refresh time. This may be useful in some cases where small amounts of 
material are displayed but the amount frequently changes, causing 
changes in intensity. In most cases, however, using synchronization 
increases flicker. 

Macro Calls: .SYNC 
.NOSYN 

Errors t 

None. 



N.2.14 .TRACK 

The .TRACK request causes the tracking object to appear on the display 
CRT at the position specified in the request. The tracking object is 
a diamond-shaped display figure which is light-pen sensitive. If the 
light pen is placed over the tracking object and then moved, the 
tracking object follows the light pen, trying to center itself on the 
pen. 

The tracking object first appears at a position specified in a 
two-word buffer whose address was supplied with the .TRACK request. 
As the tracking object moves to keep centered on the light pen, the 
new center position is returned to the buffer. A new set of X and Y 
values is returned for each light pen interrupt. 

The tracking object cannot be lost by moving it off the visible 
portion of the display CRT. When the edge flag is set, indicating a 
side of the tracking object is crossing the edge of the display area, 
the tracking object stops until moved toward the center. To remove 
the tracking object from the screen, repeat the .TRACK request without 
arguments . 

The .TRACK request may also include the address of a completion 
routine as the second argument. If a .TRACK completion routine is 
specified, the light pen interrupt handler passes control to the 
completion routine at interrupt level. The completion routine is 
called as a subroutine and the exit statement must be an RTS PC. The 
completion routine must also preserve any registers it may use. 

Macro Callt .TRACK .baddr, .croutine 

where i .baddr is the address of the two-word 

buffer containing the X and Y 
position for the track object. 

.croutine is the address of the completion 
routine . 

Errors : 

None. 

Example : 

See Section N.10. 
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N.2.15 .UNLNK 

The .UNLNK request is used before exiting from a program. In the case 
where the scroller is present, .UNLNK breaks the link, established by 
.LNKRT, between the Display Pile Handler's internal display file and 
the scroll file in the Display Monitor. The display processor is 
started cycling in the scroll text buffer, and no further graphics may 
be done until the link is established again. In the case where no 
scroller exists, the display processor is simply left stopped. 

Macro Call: .UNLNK 

Errors : 

No errors are returned. An internal link flag is checked to determine 
if the link exists. If it does not exist, the request is ignored. 



N.3 EXTENDED DISPLAY INSTRUCTIONS 

The Display File Handler offers the assembly language graphics 
programmer an extended display processor instruction set, implemented 
in software through the use of the Load Status Register A (LSRA) 
instruction. The extended instruction set includes: subroutine call, 
subroutine return, display status return, display halt, and load name 
register. 



N.3.1 DJSR Subroutine Call Instruction 

The DJSR instruction (octal code is 173400) simulates a display 
subroutine call instruction by using the display stop instruction 
(LSRA instruction with interrupt bits set) . The display stop interrupt 
handler interprets the non-zero word following the DJSR as the 
subroutine return address, and the second word following the DJSR as 
the address of the subroutine to be called. The instruction sequence 
is: 

DJSR 

Return address 

Subroutine address 

Example : 

To call a subroutine SQUARE: 

POINT ^POSITION BEAM 

100 IAT (100,1003 

100 

DJSR (THEN CALL SUBROUTINE 

.♦« 

SQUARE >T0 DRAM A SQUARE 

DRET 


The use of the return address preceding the subroutine address offers 
several advantages. BASIC/GT uses the return address to branch around 
subpicture tag data stored following the subpicture address. This 
structure is described in Section N.5.3. In addition, a subroutine may 
be temporarily bypassed by replacing the DJSR code with a DJMP 
instruction, without the need to stop the display processor to make 
the by-pass. 
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The address of the return address is stacked by the display stop 
interrupt handler on an internal subplcture stack. The stack depth is 
conditional! zed and has a default depth of 10. If the stack bottom is 
reached, the display stop interrupt handler attempts to protect the 
system by rejecting additional subroutine calls. In that case, the 
portions of the display exceeding the legal stack depth will not be 
displayed. 



N.3.2 DRET Subroutine Return Instruction 

The DRET instruction provides the means for returning from a display 
file subroutine. It uses the same octal code as DJSR, but with a 
single argument of zero. The DRET instruction causes the display stop 
interrupt handler to pop its subpicture stack and fetch the subroutine 
return address. 

Example : 



3QUAREI LONGV 

100JINTX 



>0RAW A SQUARE 



a 

UIINTX 

100 
1001INTX1MINU8X 

a 

0JINTX 

10U1MINUSX 

OHET 





IRCTURN FROM SUBPICTURE 



N.3.3 DSTAT Display Status Instruction 

The DSTAT instruction (octal code is 173420) uses the LSRA instruction 
to produce a display stop interrupt, causing the display stop 
interrupt handler to return display status data to a seven-word user 
status buffer. The status buffer must first have been set up with a 
.STAT macro call (if not, the DSTAT is ignored and the display is 
resumed) . The first word of the buffer is set non-zero to indicate the 
transfer has taken place, and the DSTAT is replaced with a DNOP 
(display NOP) . The first word is the buffer flag and the next six 
words contain name register contents, current subpicture tag, display 
program counter, display status register, display X register, and 
display Y register. After transfer of status data, the display is 
resumed. 



N.3.4 DHALT Display Halt Instruction 

The DHALT instruction (octal code is 173500) operates similarly to the 
DSTAT instruction. The difference between the two instructions is 
that the DHALT instruction leaves the display processor stopped when 
exiting from the interrupt. A status data transfer takes place 
provided the buffer was initialized with a .STAT call. If not, the 
DHALT is ignored. 
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Example : 








.STAT 


#8BUF 




MOV 


•DHALTrSTPLOC 




.IN9RT 


iDPILE 


181 


T8T 


SBUF 




BEQ 

* 


18 


SBUFl 


,BUKW 


7 


QFILEl 


POINT 






.WORD 


500,1350 




LQNGV 






• WORD 


0,400 


STPLOCl 


ONOP 
ORET 







UNIT BUFFER 
IIN8ERT DHALT 
I0ISPUY THE PICTURE 
fOHALT PROCESSED? 

INO, WAIT 



I3TATUS BUFFER 

IPOSITIQM NEAR TOP OF 12" TUBE 

(DRAW A LINE* MAYBE OVER EDGE 

HP IT 19 A ia« SCOPE. 

I8TATU8 WILL BE RETURNED AT THIS POJNT 



N.3.5 DNAME Load Name Register Instruction 

The Display File Handler provides a name register capability through 
the use of the display stop interrupt. When a DNAME instruction 
(octal code is 173520) is encountered, a display stop interrupt is 
generated. The display stop handler stores the argument following the 
DNAME instruction in an internal software register called the "name 
register". The current name register contents are returned whenever a 
DSTAT or DHALT is encountered, and more importantly, whenever a light 
pen interrupt occurs. The use of a "name" (with a valid range from 1 
to 77777) enables the programmer to label each element of the display 
file with a unique name, permitting the easy identification of the 
particular display element selected by the light pen. 



The name register contents are stacked 
restored on return from the subpicture. 

Example : 

The SQUARE subroutine with "named" sides: 

SQUAREl DNAME 
10 

LQNGV 
1001INTX 


DNAME 
11 

0JINTX 
100 
ONAME 
12 

1001INTXJMINUSX 

DNAME 



on a subpicture call and 



INAME IS 

M0 

fDRAW A SIDE 



ITHJS SIDE IS NAMfcD 

111 

ISTILL IN LONG VECTOR MODE 
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13 

ailNTX 

1 045iHIKUSX 

DRET 





>RETURN FROM SUBPICTURE 



N.4 USING THE DISPLAY FILE HANDLER 

Graphics programs which intend to use the Display File Handler for 
display processor management can be written in MACRO assembly 
language. The display code portions of the program may use the 
mnemonics described in Section N.7. Calls to the Handler should have 
the format described in Section N.6. 

The Display File Handler is supplied in two pieces, a library of MACRO 
calls and a library containing the Display File Handler modules. 



MACRO Library: 
Display File Handler: 



VTMAC.MAC 

VTHDLR.OBJ (consisting ofi) 

VTBASE.OBJ 
VTCALl.OBJ 
VTCAL2.0BJ 
VTCAL3.0BJ 
VTCAL4.0BJ 



N.4.1 Assembling Graphics Programs 

To assemble a graphics program using the display processor mnemonics 
or the Display Handler macro calls, the file VTMAC.MAC must be 
assembled with the program, and must precede the program in the 
assembler command string. 



Example : 

Assume PICTUR.MAC is a user graphics program to 
assembler command string would look like this: 

.R MACRO 
*PICTUR=VTMAC ,PICTUR 



be assembled. 



An 



N.4. 2 Linking Graphics Programs 

Once assembled with VTMAC, the graphics program must be linked with 
the Display File Handler, which is supplied as a single concatenated 
object module, VTHDLR.OBJ. The Handler may optionally be built as a 
library, following the directions in N.8.5. The advantage of using the 
library when linking is that the Linker will select from the library 
only those modules actually used. Linking with VTHDLR.OBJ results in 
all modules being included in the link. 

To link a user program called PICTUR.OBJ using the concatenated object 
module supplied with RT-11: 

.R LINK 
*PICTUR-PICTUR,VTHDLR 



N-16 



Display File Handler 



To link a program called PICTUR.OBJ using the VTLIB library built by 
following the directions in N.8.5, be sure to use the Version 2 
Linker: 

.R LINK 
*PICTUR=PICTUR, VTLIB 

* 



VTLIB (Handler Modules) : 

Module CSECT 



VTCAL1 



$GT1 



VTCAL2 



VTCAL3 



$GT2 



$GT3 



VTCAL4 



$GT4 



Contains 

.CLEAR 
.START 
.STOP 
. INSRT 
.REMOV 

.BLANK 
.RESTR 

.LPEN 

.NAME 

.STAT 

.SYNC 

.NOSYN 

.TRACK 

.LNKRT 
.UNLNK 
.SCROL 



VTBASE $GTB Memory resident base module 

containing interrupt handlers 
and internal display file 

To link a display program using overlays, the modules must be 
specified individually. The user must acquire the sources and follow 
the assembly directions in Section N.8. The modules VTCAL1 and VTCAL2 
must be simultaneously resident. For example: 

.R LINK 

*PICTUR=*PICTUR , VTBASE/C 
♦VTCAL1 , VTCAL2 , VTCAL3/0 : 1/C 
*VTCAL 4/0:1 

To link a display program to run as a foreground task: 

.R LINK 
*PICTUR=PICTUR,VTLIB/R 



N.5 DISPLAY FILE STRUCTURE 

The Display File Handler supports a variety of display file 
structures, takes over the job of display processor management for the 
programmer, and may be used for both assembly language graphics 
programming and for systems program development. For example, the 
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Handler supports the tagged subpicture file structure used by 
BASIC/6T, as well as simple file structures. These are discussed in 
this section. 



N.5.1 Subroutine Calls 

A subroutine call instruction, with the mnemonic DJSR, is implemented 
using the display stop (DSTOP) instruction with an interrupt. The 
display stop interrupt routine in the Display File Handler simulates 
the DJSR instruction, and this allows great flexibility in choosing 
the characteristics of the DJSR instruction. 

The DJSR instruction stops the display processor and requests an 
interrupt. The DJSR instruction may be followed by two or more words, 
and in this implementation the exact number may be varied by the 
programmer at any time. The basic subroutine call has this form: 

DJSR 

Return Address 

Subroutine Address 

In practice, simple calls to subroutines could look likes 

DJSR 

.WORD .+4 

.WORD SUB 

where SUB is the address of the subroutine. Control will return to 
the display instruction following the last word of the subroutine 
call. This structure permits a call to the subroutine to be easily 
by-passed without stopping the display processor, by replacing the 
DJSR with a display jump (DJMP) instruction i 

DJMP 

.WORD .+4 

.WORD SUB 

A more complex display file structure is possible if the return 
address is generalized: 

.DJSR 

.WORD NEXT 

.WORD SUB 

where NEXT is the generalized return address. This is equivalent to 
the sequence: 

DJSR 

.WORD .+4 

.WORD SUB 

DJMP 

.WORD NEXT 

It is also possible to store non-graphic data such as tags and 

pointers in the subroutine call sequence, such as is done in the 

tagged subpicture display file structure of BASIC/GT. This technique 
looks like : 
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DJSR 
.WORD 
.WORD 
DATA 



NEXT 
SUB 



NEXTs 



For simple applications where the flexibility of the DJSR instruction 
described above is not needed and the resultant overhead not desired, 
the Display File Handler (VTBASE.MAC and VTCALL.MAC) can be 
conditionally re-assembled to produce a simple DJSR call. If NOTAG is 
defined during the assembly, the Handler will be configured to support 
this simple DJSR call: 



DJSR 
.WORD 



SUB 



where SUB is the address of the subroutine. Defining NOTAG will 
eliminate the subpicture tag capability, and with it the tracking 
object, which uses the tag feature to identify itself to the light pen 
interrupt handler. 

Whatever the DJSR format used, all subroutines and the user main file 
must be terminated with a subroutine return instruction. This is 
implemented as a display stop instruction (given the mnemonic DRET) 
with an argument of zero. A subroutine then has the form* 

SUB: Display Code 
DRET 
.WORD 



N.5.2 Main File/Subroutine Structure 

A common method of structuring display files is to have a main file 
which calls a series of display subroutines. Each subroutine will 
produce a picture element and may be called many times to build up a 
picture, producing economy of code. If the following macros are 
defined i 



.MACRO 

DJSR 

.WORD 

.WORD 

.ENDM 

.MACRO 

DRET 

.WORD 

.ENDM 



CALL <ARG> 

.+4 
ARG 

RETURN 





then a main file/subroutine file structure would look liket 



j MAIN DISPLAY FILE 

t 

MAINt Display Code 
CALL SUB1 
Display Code 
CALL SUB2 



7 CALL SUBROUTINE 1 

fCALL SUBROUTINE 2 
;ETC 
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RETURN 
; DISPLAY SUBROUTINES 
SUB1: 



SUB2: 



Display Code 
RETURN 

Display Code 

RETURN 



SUBROUTINE 1 

; SUBROUTINE 2 
j ETC. 



N.5.3 BASIC/GT Subroutine Structure 

An example of another approach to display file structure is the tagged 
subpicture structure used by BASIC/GT, The display file is divided 
into distinguishable elements called subpictures, each of' which has 
its own unique tag. 

The subpicture is constructed as a subroutine call followed by the 
subroutine. It is essentially a merger of the main file/subroutine 
structure into an in-line sequence of calls and subroutines. As such, 
it facilitates the construction of display files in real time, one of 
the important advantages of BASIC/GT. 

The following is an example of the subpicture structure. Each 
subpicture has a call to a subroutine with the return address set to 
be the address of the next subpicture. The subroutine called may 
either immediately follow the call, or may be a subroutine defined as 
part of a subpicture created earlier in the display file. This 
permits a subroutine to be used by several subpictures without 
duplication of code. Each subpicture has a tag to identify it and it 
is this tag which is returned by the light pen interrupt routine. To 
facilitate finding subpictures in the display file, they are made into 
a linked list by inserting a forward pointer to the next tag. 



SUBll 



OJSR 

.wORD 

.WORD 

.WORD 

.WORD 



SUB2 
SUBl*12 
1 
SUB2«6 



istart of subpicture i 

jnext subpicture 

ijump to this subpicture 

itas « i 

ipointer to next t*g 



I BODY OF SUBPICTURE 1 



SUB2I 



DRET 



OJSR 
.WORD 
.WORD 
.WORD 
, WORD 



SUBS 

8UB2+12 

2 

SUB 3+6 



I 80UY OF SUBPICTURE 2 
ORET 
.WORD 



IRETURN PROM 
ISUBPICTURE t 

ISTART SUBPICTURE 2 

INEXT SUBPICTURE 

/JUMP TO THIS SUBPICTURE 

|TAG s 2 

|PTR TO NEXT T*G 



fRETURN FROM 
ISUBPICTURE 2 
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3UB3I 



SU84I 



0J3R 

.WORD 

,*0RD 

,*0RD 
.WORD 

DJSR 



8UB4 
SUB1*1* 



5UB4*6 



I8TART 8UBPICTUKE 3 
INEXT 8UBPICTURE 
ICOPV sub'picture 1 
IFOR THIS 8UBPICTU»E 
IBUT TAB IT 3. 
IPTR TO NEXT TAG 

»8TART SUBPICTURE 4 
IfcTC, 



N.6 SUMMARY OF GRAPHICS MACRO CALLS 



Mnemonic 



Function 



MACRO Call 
(See Note 1) 



Assembly Language 
Expansion (see 
Note 2) 



.BLANK Temporarily blanks 

a user display file. 



.CLEAR Initializes handler. 



.INSRT Inserts a call to 
user display file 
in handler's master 
display file. 



.LNKRT Sets up vectors and 
links display file 
handler to RT-11 
scroller. 

.LPEN Sets up light pen 
status buffer. 



.NAME Sets up buffer to 
receive name 
register stack 

contents. 



.NOSYN Disable power line 
sync. 

.REMOV Removes the call to 
a user display file. 



.BLANK .faddr 



.CLEAR 



, INSRT .faddr 



, LNKRT 



.LPEN .baddr 



.NAME .baddr 



.NOSYN 
.REMOV .faddr 
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.GLOBL $VBLNK 
.IF NB, .faddr 
MOV .faddr, %tl00 

ENDC 
JSR %t07, $VBLNK 

.GLOBL $VINIT 
JSR %t07, $VINIT 

.GLOBL $VNSRT 

.IF NB, .faddr 

MOV .faddr, %tO0 

.ENDC 

JSR %t07, $VNSRT 

.GLOBL $VRTLK 
JSR %t07, $VRTLK 



.GLOBL SVLPEN 

.IF NB, .baddr 

MOV .baddr, %tO0 

.ENDC 

JSR %t07, $VLPEN 

.GLOBL $NAME 

.IF NB, .baddr 

MOV .BEDDR, %tO0 

.ENDC 

JSR %t07, $NAME 

.GLOBL $NOSYN 
JSR %t07, $NOSYN 

.GLOBL $VRMOV 
.IF NB, .faddr 
MOV .faddr, %tO0 
ENDC 

■JSR %t07, $VRMOV 
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, RESTR 



.SCROL 



, START 



,STAT 



.STOP 



,SYNC 



.TRACK 



, UNLNK 



Unblanks the user 
display file. 



Adjusts monitor 
scroller parameters. 



Starts the display. 



Sets up status 
buffer. 



Stops the display. 

Enables power line 
sync. 

Enables the track 
object. 



.RESTR .faddr 



.SCROL .baddr 



.START 
.STAT .baddr 



.STOP 



.SYNC 



.TRACK .baddr, 
. croutine 



Unlinks display 
handler from RT-11 
if linked, otherwise 
leaves display stopped. 



.UNLNK 



.GLOBL $VRSTR 

IF NB, .faddr 

MOV .faddr, %tO0 

.ENDC 

JSR %t07, $VRSTR 

.GLOBL $VSCRL 

.IF NB, .baddr 

MOV .baddr, %tO0 

.ENDC 

JSR %t07, $VSCRL 

.GLOBL $VSTRT 
JSR %t07, $VSTRT 

.GLOBL $VSTPM 

.IF NB, .baddr 

MOV .baddr, %tO0 

.ENDC 

JSR %t07, $VSTPM 

.GLOBL $VSTOP 
JSR %t07, $VSTOP 

.GLOBL $SYNC 
JSR %t07, $SYNC 

.GLOBL $VTRAK 

.IF NB, .baddr 

MOV .baddr, %tO0 

.ENDC 

.IF NB, .croutine 

MOV . croutine, - 

(%t06) 
.IFF 

CLR-(%t06) 
.ENDC 
.NARG T 
.IF EQ, T 
CLR %tO0 
.ENDC 
JSR %t07, $VTRAK 

.GLOBL $VUNLK 
JSR %t07, $VUNLK 



NOTE 1 

.baddr Address of data buffer. 

.faddr Address of start of user 
display file. 

.croutine Address of .TRACK completion 
routine. 
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NOTE 2 



The lines preceded by a dot will not be 
assembled. The code they enclose may or 
may not be assembled depending on the 
conditionals . 



N.7 DISPLAY PROCESSOR MNEMONICS 



Mnemonic 



Value 



Function 



CHAR 

SHORTV 

LONGV 

POINT 

GRAPHX 

GRAPHY 

RELATV 



100000 
104000 
110000 
114000 
120000 
124000 
130000 



Character Mode 
Short Vector Mode 
Long Vector Mode 
Point Mode 
Graphplot X Mode 
Graphplot Y Mode 
Relative Point Mode 



INTO 

INT1 
INT2 
INT3 
INT4 
INT5 
INT6 
INT7 



LPOFF 
LPON 

BLKOFF 
BLKON 



2000 

2200 
2400 
2600 
3000 
3200 
3400 
3600 



100 
140 

20 
30 



Intensity 
(Dimmest) 
Intensity 
Intensity 
Intensity 
Intensity 
Intensity 
Intensity 
Intensity 



(Brightest) 

Light Pen Off 
Light Pen On 

Blink Off 
Blink On 



LINE0 
LINE1 
LINE2 
LINE 3 



4 
5 
6 
7 



Solid Line 
Long Dash 
Short Dash 
Dot Dash 



DJMP 
DNOP 
STATSA 



160000 
164000 
170000 



Display Jump 
Display No Operation 
Load Status A 
Instruction 



LPLITE 
LPDARK 

ITAL0 
ITAL1 



200 
300 

40 
60 



Light Pen Hit On 
Light Pen Hit Off 

Italics Off 
Italics On 



SYNC 
STATSB 



174000 



Halt and Resume in 
Sync 

Load Status B 
Instruction 
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INCR 

(Vector/Point Mode) 

INTX 



MAXX 
MAXY 

MINUSX 
MINUSY 

(Short Vector Mode) 

SHIPTX - 

MAXSX 
MAXSY 

MISVX 

MISVY - 



Value 
100 



40000 



1777 
1377 

20000 
20000 



200 

17600 
77 

20000 
100 



Function 
Graphplot Increment 



Intensity Vector or 
Point 

Maximum X Component 
Maximum Y Component 

Negative X Component 
Negative Y Component 



Maximum X Component 
Maximum Y Component 

Negative X Component 
Negative Y Component 



N.8 ASSEMBLY INSTRUCTIONS 



N.8.1 General Instructions 

All programs can be assembled in 16K, using RT-11 MACRO. All 
assemblies and all links should be error free. The following 
conventions are assumed: 

1. Default extensions are not explicitly typed. These are .MAC 
for source files, .OBJ for assembler output, and .SAV for 
Linker output. 

2. The default device (DK) is used for all files in the example 
command strings. 

3. Listings and link maps are not generated in the example 
command strings. 



N.8. 2 VTBASE 

To assemble VTBASE with RT-11 link-up capability: 

.R MACRO 
*VTBASE-VTBASE 
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N.8.3 VTCAL1 - VTCAL4 

To assemble the modules VTCALl through VTCAL4: 



.R MACRO 

*VTCAL1=VTCAL1 

*VTCAL2=VTCAL2 

*VTCAL3=VTCAL3 

*VTCAL4-VTCAL4 



N.8.4 VTHDLR 

To create the concatenated handler module: 

.R PIP 

* VTHDLR. OB J=VTCAL1 .OBJ , VTCAL2 . OBJ , VTCAL3 .OBJ , VTCAL4 . OBJ , VTBASE . OB J/B 



N.8.5 Building VTLIB.OBJ 

To build the VTLIB library: 

.R LIBR 
*VTLIB=VTHDLR. OBJ 



N.9 VTMAC 

.NLI3T 
I VTMAC 

; LIBRAHY DF MACRO CALLS AND MNEMONIC DEFINITIONS 
f FOR THE VT11 DEVICE SUPPORT PACKAGE 

t DEC-U-OVTMA-B-LA 

I COPYRIGHT (C) 197a 

I DIGITAL EQUIPMENT CORPORATION 

I MAYNARQ, MASSACHUSETTS 0175« 

I MAY 197* 

» THE INFORMATION IN THIS DOCUMENT 19. SUBJECT TO 

t CHANGE WITHOUT NOTICE AND SHOULD NOT BE CONSTRUED 

I A3 A COMMITMENT BY DIGITAL EQUIPMENT CORPORATION. 

I DEC ASSUMES NO RESPONSIBILITY FOR ANY ERRORS THAT 

I MAY APPEAR IN THIS DOCUMENT, 

I DEC ASSUMES NO RESPONSIBILITY FOR THE USE 
I OR RELIABILITY OF ITS SOFTWARE ON EQUIPMENT 
I WHICH IS NOT SUPPLIED BY DEC, 

t THIS SOFTWARE IS FURNISHED TO PURCHASER UNDER A 

t LICENSE FOR USE ON A SINGLE COMPUTER SYSTEM AND 

J CAN BE COPIED (WITH INCLUSION OF DEC'S COPYRIGHT 

> NOTICE) ONLY FOR USE IN SUCH A SYSTEM, EXCEPT AS MAY 

I OTHERWISE BE PROVIOEO IN WRITING BY DEC. 

N-25 



Display File Handler 

) VTMAC IS A LI&RARY OF MACRO CALLS WHICH PROVIDE SUPPORT 

> OF THE VTU DISPLAY PROCESSOR. THE MACROS PRODUCE CALLS 

f TO THE VTU DEVICE SUPPORT PACKAGE, USING GLOBAL REFER- 

I ENCES. 

I MACRO TO GENERATE A MACRO WITH ZERO ARGUMENTS. 

.MACRO MAC0 NAME, CALL 

.MACRO NAME 

.GL06L CALL 

JSR X"07,CALL 

.ENDM 

.ENDM 

* MACRO TO GENERATE A MACRO WITH ONE ARGUMENT 

.MACRO MAC1 NAME, CALL 

.MACRO NAME ARG 

.IF NB,ARG 

MOV ARG,X*O0 

.ENDC 

.GLOBL CALL 

JSR X"07,C*LL 

.ENDM 

.ENDM 

1 MACRO TO GENERATE A MACRO WITH TWO OPTIONAL ARGUMENTS 

.MACRO MAC2 NAME, CALL 

.MACRO NAME ARG1,ARG2 

.GLOBL CALL 

.IF NB.ARGi 

MOV ARG1,X-O0 

.ENDC 

.IF N8,ARG2 

MOV AKG2,-(X-0fc) 

.Iff 

CLR -CX*06) 

.NARG T 

•IF EQ,T 

CLR X*"O0 

.ENDC 

.ENDC 

JSR X"07,CALL 

.ENDM 

.ENDM 
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I MACRO LIBRARY FOR VT1H 

MACB <, CLEAR*, <$VINIT> 

MAC0 <.ST0P»,«SVST0P» 

MAC0 <, START*, «$VSTRT> 

MAC0 <,SYNC>,«$SYNO 

MAC0 «.N0SYN*,«$N0SYN» 

MAC0 «,UNLNK»,<$VUNLK» 

MAC1 «,INSRT»,<8VNSRT> 

MACl «.REMQV*,«SVRMOV» 

MACl «t, BLANK*, «$VBLNK* 

MACl «.RESTR*,«SVRSTR> 

MACl «,STAT>,«SVSTPMj. 

MACl «,LPEN>,«SVIPEN» 

MACl <,3CR0L>,«$VSCRL> 

MACl «,NAME*,«SNAME> 

MAC2 «. TRACK*, <$VTRAK> 

MAC0 <.UNKRT>#<8VRTLK> 

I MNEMONIC DEFINITIONS FOR THE VTll DISPLAY PROCESSOR 

t 

DJMPM60000 /DISPLAY JUMP 

DNOPM64800 >DI8PLAY NOP 

DJSR-173400 /DISPLAY SUBROUTINE CALL 

QRET*173400 /DISPLAY SUBROUTINE RETURN 

DNAME«173520 /SET NAME REGISTER 

DSTATM73420 /RETURN STATUS DATA 

DHALTM73500 /STOP DISPLAY AND RETURN STATUS DATA 

/ 

CHARM00000 /CHARACTER MODE 

SnORTV»10«000 /SHORT VECTOR MODE 

LONGVM10000 (LONG VECTOR MODE 

PQINT»114000 /POINT MODE 

GRAPHXM20000 /GRAPH X MODE 

GRAPHYM24000 /GRAPH Y MODE 

RELATVM30000 RELATIVE VECTOR MODE 

I 

INT0«2000 IINTENSITY 

INTi»2200 

INT2-2400 

INT3»2600 

INT4«3000 

INT5»3200 

INT6«3«00 

INT7»3600 

I 

LPOFFM00 /LIGHT PEN OFF 

LPON-H0 ILIGHT PEN ON 

BLKOFF«20 /BLINK OFF 

BLKUN>30 /BLINK ON 

LINE0»<l /SOLID LINE 

LINE1-5 /LONG DASH 

LIN£2«6 /SHORT OASH 

HNE3"7 /DOT OASH 

I 
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STATSA»170000 1L0AD STATUS REG A 

LPLITE-200 llNTENSIFY ON LPEN MIT 

LPDAHK,«300 JUON'T INTENSIFY 

ITA10I40 ; ITALICS OFF 

ITAL1»60 UTALICS ON 

SYNC"-U >POwER LINE SYNC 

J 

STATSB«17400I2 

INCR"100 

INTX»«0000 

MAXXM777 

MAXYM377 

MINUSX»20000 

MINU8Y«20000 

MAXSXil76B0 

MAX3Y»77 

MISVX«20000 

MISVY«100 

.LIST 



N.IO EXAMPLES USING GTON 

EXAMPLE #1 RT-11 MACRO VM02-.06 9-AUG-74 PAGE 4 

2 .TITLE EXAMPLE »1 

3 I 

4 J THIS EXAMPLE USES THE .LPEN STATUS BUFFER AnD Th£ 

5 ) NAME REGISTER TO MODIFY A DISPLAY FILE WITH ThE LIGHT PEN, 

6 I 

7 000000 K0»X0 
3 000001 Kl»U 

9 000007 PC"*7 

10 0001044 JSw«44 |JU8 STATUS WO«0 

11 

12 .MCALL ,TT1NR,.EXIT#. PRINT 

13 00000 STARTl .LNKRT JLlNK. TO MONITOs 

14 00004 100004 bPL IS JLlNK UP ERROR? 

15 00006 .PRINT WEMStt >YtS, PRINT MESSAGE 

16 00014 .EXIT >AND EXIT, 

17 00016 l$l .SCROL *SCBUF IADJUST SCROLL 

18 00086 .PRINT «MSG 

19 00034 .INSRT #DFILE MNSERT DISPLAY FILE 

20 00044 .LPEN »L6UF JSET UP LPEN BUFFER 

21 00054 032/37 BIS »100-»MjSw JSET JSw FOR TTINR 
21 000100 

21 000044 

22 00062 00S/6/ LT5TJ TST LBUF FLIGHT PEN HIT? 

22 00007v3 

23 00066 001003 BNE IS HYfeS 

24 00070 .TTINR JNO, ANY TT IMHijT? 
29 00072 103023 bCC EXIT »YfcSi EXIT 

26 00074 000772 BR LTST JNO, LOOP AGAIN 

27 00076 016777 l$l MOV I2,#1PTR JRESTORE PREVIOUS CODE 
27 000074 

27 000102 

28 00104 1016701 MQV LBUF + 2,Rl »GET NAME VALUE 
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28 00005W 

29 00110 005301 UEC Ri /SUBTRACT ONE 

30 00112 0063^1 ASL Hi MULTIPLY SY T"0 

31 00114 060701 ADO PCR1 /USE TO INDEX 

32 30116 062701 ADO *DT ABL-. , R 1 /OFT TABLfc OTAbt. 

32 000062 

33 00122 011167 MOV (KlJflPTR /MOVE AOOR INTQ IPTR 

33 00006O 

34 00126 016/77 MQV H.HPTK /MODIFY THAT CO-QE 
34 000042 

34 000052 

35 00134 005067 tLH LSUF /CLEAR BUFFER FLAG TO 

35 000016 

36 /ENABLfc ANOTHER LP HIT. 

37 00140 000760 BR LTST /LOOP AGAIN 

38 00142 022700 EXiTI CMP W12.R0 /LINE FEED? 
38 000012 

3» 00146 001345 BNE LTST /NO, GET ANOTHER 

40 001&0 .UNLNK /UNLINK FROM MONITOR 

41 00154 .EXIT 

42 00136 LBUFI .8LKW 7 /L^EN STATUS BUFFER 

43 00174 103370 Hi .WQRO CHAR 1 INT5 1 BL*ON { LPQN 

44 00176 103160 I2» .wQRD CHAR t INT4 1 BLKOFF J L^ON 

43 00200 000252»OTABL» .*QRD D1,Q2,D3 /TABLE OF DISPLAY FILE 

45 302(92 000272' 



EXAMPLE #1 RT-ll MACRO VM02-06 9-AUG-74 PAGE 4+ 

45 00204 000312' 

46 /LOCATIONS TO Be MODIFIED 

47 00206 000252'IPTR» .WORD Di /PREVIOUS LOCATION MODIFIED 

48 00210 000002 SCUUFl ,wQRD 2 /SCROLL LINE COUNT 

49 00212 001000 .WORD 1000 /SCROLL TOP V PqS, 
90 00214 041 EMSftl .ASCIZ /IERRORI/ /ERROR MESSAGE 

90 014215 105 

90 00216 122 

50 00217 122 
50 00220 117 
50 00221 122 
50 00222 041 

50 00223 000 

51 .fcVEN 

52 00224 105 MSU| .ASCIZ /EXAMPLE *!/ 11,0, MESSAGE 
52 00225 130 

52 00226 16)1 

52 00227 lit) 

52 00230 120 

52 00231 114 

52 00232 103 

52 0*0233 04* 

52 00234 043 

52 00235 061 

52 00236 0(o0 

53 .EVEN 

54 / 

55 » DISPLAY FILE FOR EXAMPLE *i 

56 / 

57 00240 114000 DFILEJ POINT 

58 00242 000100 100 

59 00244 U00500 600 

60 00246 173520 DNAME 

61 00250 00HB01 1 

62 00252 103160 1>1» CHAR 1 BLKOFF 1 1NT4 UPON 
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63 010254 U7 


.ASCII 


/ONE./ 






63 00295 116 










63 00236 1®3 










63 00297 096 










64 00260 U4020 


POINT 








05 00262 000100 


100 








66 00264 000000 


300 








67 0026b 173620 


ONAME 








68 00270 000002 


2 








69 00272 103160 Q2» 


CHARJBLK0FFJlNT4ilP0N 






70 00274 124 


.ASCII 


/TWO./ 






70 00275 127 










70 00276 117 










70 00277 056 










71 00300 114000 


POINT 








72 00302 000100 


100 








73 0(0304 000100 


100 








74 00306 173520 


UNAME 








75 00310 000003 


3 








76 00312 1KI3160 031 


Chahjbl 


KOFF JINT4JLP0N 






77 00314 124 


.ASCII 


/THREE,/ 






77 00316 110 
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77 00316 122 










77 00317 105 










77 00320 10S 










77 00321 096 










78 00322 173400 


ORET 








79 00324 B00000 











80 000000< 


.END 


START 
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SYMBOL TABLE 










BLKOFF* 000020 


BLKQN » 


000B3? 


CHAR ■ 


100000 


DFlLt 000240K 


WMALT ■ 


173500 


OJMP ■ 


160000 


DJSR « 1734*0 


QNAME * 


173520 


ONOP ■ 


164000 


DHET • 173400 


OSTAT ■ 


173420 


DTABL 


000200R 


01 0002S2N 


02 


0002/2R 


D3 


000312R 


EMSG 000214* 


EXIT 


000142R 


GRAPHXb 


120000 


GRAPHY* 124000 


iNCR » 


000100 


INTX a 


040000 


INTfcj • 002000 


INT1 ■ 


002200 


INT2 • 


002400 


INT3 ■ 002600 


INT4 » 


003000 


INT5 ■ 


003200 


INT6 * 003400 


1NT7 ■ 


003600 


IPTR 


000206R 


ITALB • 000040 


ITAL1 ■ 


000060 


11 


000174K 


12 000176H 


JSW ■ 


000044 


LBUF 


000156R 


LINgW * 000004 


LINES, ■ 


000005 


LINE2 ■ 


000006 


LINE3 • 000007 


LQNGV ■ 


110000 


LPOAHKi 


000300 


LPLlTEt 000200 


LPQFF ■ 


000100 


LPON b 


000140 


LTST 000062K 


MAXSX ■ 


017600 


MAXSY b 


000077 


MAXX • 001777 


MAXY ■ 


001377 


MINUSX" 


020000 


MINU4Y« 020000 


HISVX ■ 


020000 


MISVY ■ 


00010a 


MSG 000224H 


PC « 


X000007 


POINT b 


11400-3 


RELATVB 130000 


R0 » 


X000000 


Rl B" 


£000001 


SCBUK 000210* 


bHORTV" 


104000 


START 


000000R 


5TATSA» 17000S" 


STATSB" 


174000 


SYNC " 


400004 


SVLPtNi ****** 6 


»VNS»T» 


****** t> 


$VHTLK« 


****** 5 


SVSCNL* ****** G 


*VUNLK« 


****** Q 






, ASS, 000000 000 










U00346 001 










ERRQKS UtTtcUDi 











FREE QQAil 1^117, WORDS 
MANE*liLP»*VTMAC,MANEXl 
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EXAMPLE #2 RT-il MACRO VM02-06 9.AUG-74 PAGE 4 

2 .TITLE EXAMPLE #2 

3 I 

4 ; THIS EXAMPLE USES THE TRACKING OBJECT AND THE TRACK 

5 I COMPLETION ROUTINE TO CAUSE A VECTOR TO FOLLOW 

6 I THE LIGHT PEN FROM A SET POINT AT (500,5001, 

7 I 

8 0006100 R0»X(9 

9 000001 M*Xl 

10 000006 5Pt%6 

11 000007 PC«X7 

12 .MCALL .EXIT, .TTYIN, .PRINT 

13 00000 STARTI .LNKRT ILlNK TO MONITOR 

14 00004 100004 BPL is ;link up ERROR? 

15 00006 .PRINT *EMSG JYES, INFORM USER 

16 00014 .EXIT IAND EXIT 

17 00016 IS! .INSRT #DPILE >INSERT DISPLAY FILE 

18 00026 .TRACK #TBUF,*TCOM IDI3PLAY TRACK OBJECT 

19 00042 004767 J5R PC, WAIT IWAIT FOR <CR> 

19 000006 

20 00046 .UNLNK IUNLINK FROM mOnITQR 

21 00032 .EXIT 

22 00064 WAITI .TTYIN KJET CMAK, FRQM TTY 

23 00060 022700 CMP #12, K0 ;LlNE KEtO? 

23 000012 

24 00064 001373 BNE WAIT JND, SET ANOThEs 

25 00066 000207 RTS PC 

26 00070 W00600 TBUFI .wQRD 600,600 /TRACK BUFFER InITED TO 

26 00072 1000600 

27 fSTART TRACK AT (S00,50ia) 

28 I 

29 I TRACK COMPLETION ROUTINE ENTERED AT INTERRUPT LEVEL 

30 > FROM DISPLAY FILE HANDLER WITH DISPLAY STOPPED. 

31 I USED TU UPDATE DISPLAY FILE WITH DATA FROM TbuF. 

32 > 

>SAVE Rl 
>NEX X 

INE* X - OLD X 

JPGSITIVE DIFFERENCE? 
>NO, SO MAKE POSITIVE 
fBUT SET MINUS 9IT 

jalso set intensify bit 

fTMEN STORE IN 0FILE. 

INEw Y 

JNEW Y - OLD Y 

fPOSITIVfe DIFFERENCE? 
JNO,SU MAKE POSITIVE 
»AND SET MINUS BIT 

ITHEN STORE IN DFILE 



33 00074 


010146 


TCOMI 


MOV 


R1,-CSP) 


34 00076 


016701 




MOV 


TBUF,R1 


34 


177768 








35 00102 


166/01 




SUB 


0X,R1 


35 


000052 








36 00106 


100003 




BPL 


IS 


37 00110 


005401 




NEC 


Rl 


38 90112 


052701 




BIS 


*MINUSX,Rl 


38 


020000 








39 00116 


052701 


U« 


BIS 


#INTX,R1 


39 


040000 








40 00122 


010167 




MOV 


R1,DX 


40 


000040 








41 00126 


016701 




MOV 


TBUF*2,Ri 


41 


177740 








42 00132 


166701 




SUB 


0Y,R1 


42 


000024 








43 00136 


100003 




BPL 


2$ 


44 00140 


005401 




NE& 


Rl 


45 00142 


052701 




BIS 


#MINUSX,R1 


45 


020000 








46 00146 


010167 


2Sf 


MOV 


Rl,OY 


46 


000016 
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EXAMPLE *2 RT-U MACRO VM02-06 9-AUG-74 PAGE 4 + 

47 0(0152 012001 MOV (SP)*,R1 (RESTORE Rl 

48 0B184 000207 NTS PC IEXIT PROM COMPLETION ROUTINE 

49 I 

50 J DISPLAY PILE FOR EXAMPLE #2 

51 I 

52 00156 114000 OPlLEl POINT /SET POINT AT 

53 00160 000500 QX« 500 

54 00162 000500 OYI 500 1(500,500} 

55 00164 113000 L0NSV1INT4 »QRAW A VECTOR 

56 00166 000000 OX* tHURD /INITIALLY NOwH£R£ 

57 00170 000000 DY« .WORD 

58 00172 17340*3 URET >0ISPLAY PILE EnO 

59 00174 000000 

60 00176 123 EM5GI .ASCIZ /SORHY, THERE SfcfcMS TO BE A PWOBLEM/ 
60 00177 117 

60 00200 122 
60 0io20l 122 
60 00202 131 
60 00203 054 
60 00204 040 
60 00205 124 
60 00206 114 
60 00207 105 
60 00210 122 
60 00211 105 
60 00212 040 
60 00213 123 
60 00214 105 
60 00215 105 
60 0^216 115 
60 00217 123 
60 00220 040 
60 00221 124 
60 00222 117 
60 00223 040 
60 010224 102 
60 00225 105 
60 00226 040 
60 00227 101 
60 00230 040 
60 00231 120 
60 00232 122 
60 00233 117 
60 00234 102 
60 0*235 114 
60 00236 105 

60 00237 lib 
50 00240 000 

61 .EVEN 

62 000000" .ENO START 
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EXAMPLE 


*2 RT«il 1 


1ACRG VM02 


!-06 9«AUG«74 


PAGE 4+ 




SYMBOL TABLE 












BL*0FF» 


000020 




8LK0N • 


000030 


CHAR * 


100000 


oriLfc 


000186* 




UMALT » 


173500 


DJMP ■ 


160000 


DJSR ■ 


173400 




ONAME • 


173320 


DNOP * 


164000 


DR6T • 


1734100 




OSTAT • 


173420 


OX 


000166R 


DV 


000170S 




EMSG 


000176R 


GRAPHX» 


120000 


CRAPHyt 


124000 




1NCR * 


000100 


INTX » 


040000 


INTa ■ 


0^2000 




INTI * 


002200 


JNT2 1 


002400 


INT3 ■ 


002600 




1NT4 • 


003000 


INTS » 


003200 


INT6 " 


003400 




INT7 * 


003600 


ITAL0 » 


000040 


ITALl • 


000060 




LINE0 ■ 


000004 


HNE1 ■ 


000005 


LINES • 


000006 




LINE3 « 


000007 


LONGV « 


110000 


LPDANKi 


000300 




LPLITE" 


000200 


LPOFF • 


00010*! 


LPQN ■ 


000140 




MAXSX ■ 


017600 


HAXSY ■ 


000077 


MAXX * 


0W1777 




MAXY • 


001377 


MINUSX" 


020000 


MINUSYi 


020000 




MISVX ■ 


020000 


misvy ■ 


000100 


OX 


000160R 




OY 


0001&2R 


PC •; 


(000007 


POINT • 


1140012 




«ELATV» 


130000 


R0 ■: 


(000000 


Rl <! 


(000001 




SHORTV" 


104000 


SP «: 


(000006 


START 


000000R 




STATSA" 


170000 


STATS8« 


174B0i3 


SYNC * 


000004 




TBUF 


000070R 


TCUM 


000H74R 


WAIT 


000054H 




*VNS«T« 


****** G 


$VRTLK« 


****** 1 


SVTR**" 


****** g 




SVUNLK" 


****** G 






. ASS. 


000000 
000242 


000 
001 










ERRORS uSTECTEDi 













FREE COKE' 1»022. woROS 
MANEX2,LPl»VTMAC,MANEX2 
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APPENDIX 
SYSTEM SUBROUTINE LIBRARY 



0.1 INTRODUCTION 

The RT-11 FORTRAN System Subroutine Library (SYSLIB) is a collection 
of FORTRAN-callable routines which allow a FORTRAN user to utilize 
various features of RT-11 Foreground/Background (F/B) and Single-Job 
(SJ) Monitors. SYSLIB also provides various utility functions, a 
complete character string manipulation package, and 2-word integer 
support. SYSLIB is provided as a library of object modules to be 
combined with FORTRAN programs at link-time. 

The user of SYSLIB should be familiar with Chapters 1, 2, and 9 of 
this manual. This appendix assumes that FORTRAN users are familiar 
with the PDP-11 FORTRAN Language Reference Manual and the RT-11/RSTS/E 
FORTRAN IV User's Guide. 

The following are some of the functions provided by SYSLIB. 

• Complete RT-11 I/O facilities, including synchronous, 
asynchronous, and completion-driven modes of operation. 
FORTRAN subroutines may be activated upon completion of an 
input/output operation. 

• Timed scheduling of asynchronous subjobs (completion 
routines) . (F/B only) 

• Complete facilities for interjob communication between 
Foreground and Background jobs (F/B only) . 

• FORTRAN interrupt service routines. 

• Complete timer support facilities, including timed suspension 
of execution (F/B only), conversion of different time formats, 
and time-of-day information. These timer facilities support 
either 50- or 60-cycle clocks. 

• All auxiliary input/output functions provided by RT-11, 
including the capabilities of opening, closing, renaming, 
creating, and deleting files from any device. 

• All monitor-level informational functions, such as job 
partition parameters, device statistics, and input/output 
channel statistics. 

• Access to the RT-11 Command String Interpreter (CSI) for 
acceptance and parsing of standard RT-11 command strings. 

• A character string manipulation package supporting 
variable-length character strings. 

• INTEGER*4 support routines that allow 2-word integer 
computations. 

SYSLIB allows the FORTRAN user to write almost all application 
programs completely in FORTRAN with no assembly language coding. 
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Assembly language programs may also utilize SYSLIB routines (see 
Section 0.1.3) . 



0.1.1 Conventions and Restrictions 

In general, the SYSLIB routines were written for use with RT-11 V2B 
and FORTRAN IV V1B. The use of this SYSLIB package with prior 
versions of RT-11 or FORTRAN will lead to unpredictable results. 

Programs using IFEEK, IPOKE, and/or ISPY to access FORTRAN, monitor, 
hardware, or other system specific addresses are not guaranteed to run 
under future releases or on different configurations. Suitable care 
should be taken with this type of coding to document precisely the use 
of these access functions and to check a referenced location's usage 
against the current documentation. 

The following must be considered when coding a FORTRAN program that 
uses SYSLIB. 

.1. Various functions in the SYSLIB package return values that 
are of type integer, real, and double precision. If the user 
specifies an IMPLICIT statement that changes the defaults for 
external function typing, he must explicitly declare the type 
of those SYSLIB functions that return integer or real 
results. Double precision functions must always be declared 
to be type DOUBLE PRECISION (or REAL*8) . Failure to observe 
this requirement will lead to unpredictable results. 

2. All names of subprograms external to the routine being coded 
that are being passed to scheduling calls (such as ISCHED, 
ITIMER, IREADF, etc.) must be specified in an EXTERNAL 
statement in the FORTRAN program unit issuing the call. 

3. Certain arguments (noted as such in the individual routine 
descriptions) to SYSLIB calls must be located in such a 
manner as to prohibit the RT-11 USR (User Service Routine) 
from swapping over them at execution time. This is 
accomplished by issuing a SET USR NO SWAP command before the 
job is entered, by using the /U switch at compile time, or by 
assuring that the routine argument is located in the memory 
image in such a way as to not be swapped over. The latter 
may be accomplished by changing the order of the object 
modules and libraries as specified to the linker. If the USR 
is swapping, it swaps over the first 2K of the program. The 
default case, for example, swaps the USR at 1000 octal to 
11000 octal; arguments being passed to the USR must be kept 
out of this area. (See Section 0.1.3 for further 
information. ) 

4. Quoted-string literals are useful as arguments of calls to 
routines in the SYSLIB package, notably the character string 
routines. These literals are allowed in subroutine calls 
(i.e., those invoked by the CALL statement), but they are 
explicitly prohibited in function calls (i.e., those invoked 
by the appearance of the function name followed by an 
argument list in an expression). See Sections 0.1.2 and 
0.2.4 for further information. 

5. Certain restrictions apply to completion or interrupt 
routines; see Section 0.2.1 for these restrictions. 
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0.1.2 Calling SYSLIB Subprograms 

SYSLIB subprograms are called in the same manner as user-written 

subroutines. SYSLIB includes both FUNCTION subprograms and SUBROUTINE 

subprograms. FUNCTION subprograms receive control by means of a 

function reference, represented in this appendix as: 

i = function name ({arguments}) 

SUBROUTINE subprograms are invoked by means of a CALL statement, i.e., 

CALL subroutine name { (arguments) } 

All routines in SYSLIB may be called as FUNCTION subprograms if the 
return value is desired, or as SUBROUTINE subprograms if no return 
value is desired. For example, the LOCK subroutine can be referenced 
as either: 

CALL LOCK 

or 

I = L0CK() 

Note that routines that do not explicitly return function results will 
produce meaningless values if referenced as functions. In the 
following descriptions, the more common usage (function or subroutine) 
is shown. 



0.1.3 Using SYSLIB with MACRO 

The calling sequence is standard for all subroutines, including 
user-written FORTRAN subprograms and assembly language subprograms. 
SYSLIB routines may be used with MACRO programs by passing control to 
the SYSLIB routine with the following instruction: 

JSR PC, routine 

Register five points to an argument list having the following format: 



R5 



V 



undefined 



# of arguments 



address of arg, 



#1 



address of arg, 



#2 



address of arg. #n 



0-3 



System Subroutine Library 



Control is returned to the calling program by use of the instruction: 
RTS PC 

The following is an example of calling a SYSLIB function from an 
assembly language routine. 



.GLOBL JMUL 



; GLOBAL FOR JMUL 



MOV #LIST,R5 
JSR PC, JMUL 
CMP #-2,R0 
BEQ OVRFL 



POINT R5 TO ARG LIST 
CALL JMUL 

CHECK FOR OVERFLOW 
BRANCH IF ERROR 



LIST: 


.WORD 


3 




.WORD 


OPR1 




.WORD 


OPR2 




.WORD 


RESULT 


OPR1: 


.WORD 


100 




.WORD 





OPR2: 


.WORD 


10 




.WORD 


10 


RESULT: 


.BLKW 
.END 


2 



ARG LIST, 3 ARGS 

ADDR OF 1ST ARG 

ADDR OF 2ND ARG 

ADDR OF 3RD ARG 

LOW-ORDER VALUE OF 1ST ARG 

HIGH-ORDER VALUE OF 1ST ARG 

LOW-ORDER VALUE OF 2ND ARG 

HIGH-ORDER VALUE OF 2ND ARG 

2-WORD RESULT (LOW ORDER, HIGH ORDER) 



The following routines can be used only with FORTRAN: 

GETSTR 

IASIGN 

ICDFN 

IFETCH 

IGETC 

ILUN 

INTSET 

IQSET 

IRCVDF 

IREADF 

ISCHED 

ISDATF 

ISPFNF 

ITIMER 

IWRITF 

PUTSTR 

SECNDS 

User-written assembly language programs that call SYSLIB subprograms 
must preserve any pertinent registers before calling the SYSLIB 
routine and restore the registers, if necessary, upon return. 

Function subprograms return a single result in the registers. The 
register assignments for returning the different variable types are: 

Integer, Logical functions - result in R0 
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Real functions - high-order result in RO, low-order result in Rl 

Double Precision functions - result in R0-R3, lowest order result 

in R3 

Complex functions - high-order real result in RO, low-order real 

result in Rl, high-order imaginary result in 
R2, low-order imaginary result in R3 

User-written assembly language routines which interface to the FORTRAN 
Object Time System (OTS) must be aware of the location of the RT-11 
USR (User Service Routine) . If a user routine requests a USR function 
(e.g., IENTER, LOOKUP), or if the USR is invoked by the FORTRAN OTS, 
the USR will be swapped into memory if it is nonresident. The FORTRAN 
OTS is designed so that the USR can swap over it. User routines must 
be written to allow the USR to swap over them or must be located 
outside the region of memory into which the USR will swap. 

User interrupt service routines and completion routines, because of 
their asynchronous nature, must be further restricted to be located 
where the USR will not swap. The USR (if in a swapping state) will 
always swap over the area of memory that starts at the program initial 
stack pointer address; the USR occupies 2K words. Interrupt and 
completion routines (and their data areas) must not be located in this 
area. The best way to accomplish this is to examine the link map, 
determine whether the USR will swap over an assembly language or 
FORTRAN asynchronous routine, and, if so, change the order of object 
modules and libraries as specified to the linker. Continue this 
process until a suitable arrangement is obtained. 

To remove these restrictions, the user must make the USR resident 
either by specifying the /U switch to the FORTRAN compiler (when 
compiling a program to be run in the background of F/B or under S-J) 
or by issuing the SET USR NOSWAP command before executing the program. 



0.1.4 Running a FORTRAN Program in the Foreground 

The FRUN monitor command must be modified to include various SYSLIB 
functions. Section G.l explains the formula used to allocate the 
needed space when running a FORTRAN program as a foreground job. This 
formula: 

x = {l/2{378+(29*N)+(R-136)+A*512) }} 

must be modified for SYSLIB functions as follows: 

The IQSET function requires the formula to include additional space 
for queue elements (qleng) to be added to the queue: 

x = U/2{378+(29*N)+(R-136)+A*512) }}+{7*qleng} 

The ICDFN function requires the formula to include additional space 
for the integer number of channels (num) to be allocated. 

x = U/2{378+(29*N)+(R-136)+A*512) }}+{6*num} 

The INTSET function requires the formula to include additional space 
for the number of INTSET calls (INTSET) issued in the program. 
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{1/2 {378+(29*N)+(R-136)+A*512}}+{25*INTSET} 



Any SYSLIB calls, including INTSET, that invoke completion routines 
must include 64(10) words plus the number of words needed to allocate 
the second record buffer (default is 68(10) words). The length of the 
record buffer is controlled by the /R switch to the FORTRAN compiler. 
If the /R switch is not used, the allocation in the formula must be 
132(10) words. 

x = {l/2{378+(29*N)+(R-136)+A*512}}+{64+R/2> 

If the /N option does not allocate enough space in the foreground on 
the initial call to a completion routine, the following message 
appears : 

?ERR 0, NON-FORTRAN ERROR CALL 

This message also appears if there is not enough free memory for the 
background job or if a completion routine in the Single-Job monitor is 
activated during another completion routine. In the latter case, the 
job aborts. F/B should be used for multiple active completion 
routines. 



0.1.5 Linking with SYSLIB 

SYSLIB is provided on the distribution media as a file of concatenated 
object modules (SYSF4.0BJ) . If this file is linked directly with the 
FORTRAN program, all SYSLIB modules will be included whether they are 
used or not. For example: 

^R LINK 
*PROG=PROG , SYSF4/F 

A library can be created by using the librarian to transform SYSF4 
into a library file (SYSLIB) as follows: 

^.R LIBR 
iSYSLIB=SYSF4 

When a library is used, only the modules called will be linked with 
the program. For example: 

^R LINK 
*PROG=PROG,SYSLIB/F 

The following example links the object module EXAMPL.OBJ into a single 
save image file EXAMPL.SAV and produces a load map file on LP:. 
SYSLIB and the default FORTRAN library (FORLIB.OBJ) are searched for 
any routines that are not found in other object modules. 

^R LINK 

*EXAMPL , LP : =EXAMPL , SYSLIB/F 

If the FORTRAN library is explicitly specified in the command string, 
SYSLIB must precede it, i.e., 

± R LINK 

±TEST=TEST , SYSLIB , FPULIB 
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is an acceptable command string, but the following is not: 
*TEST=TEST, FPULIB , SYSLIB 

0.2 TYPES OF SYSLIB SERVICES 

Ten types of services are available to the user through SYSLIB. These 
are: 



File-Oriented Operations 
Data Transfer Operations 
Channel-Oriented Operations 
Device and File Specifications 
Timer Support Operations 
RT-11 Service Operations 
INTEGER*4 Support Functions 
Character String Functions 
Radix-50 Conversion Operations 



Table 0-1 alphabetically summarizes the SYSLIB subprograms in each of 
these categories. Those marked with an asterisk (*) are allowed only 
in a Foreground/Background environment. 



Table 0-1 
Summary of SYSLIB Subprograms 



Function 
Call 


Section 


Purpose 


File-Orient 


ed Operation 


s 


CLOSEC 


0.3.3 


Closes the specified channel. 


IDELET 


0.3.19 


Deletes a file from the specified device. 


IENTER 


0.3.22 


Creates a new file for output. 


IRENAM 


0.3.37 


Changes the name of the indicated file to a 
new name . 


LOOKUP 


0.3.66 


Opens an existing file for input and/or output 
via the specified channel. 


Data Transf 


er Functions 




*IRCVD 
*IRCVDC 
*IRCVDF 
*IRCVDW 


0.3.35 


Receives data. Allows a job to read messages 
or data sent by another job in an F/B environ- 
ment. The four modes correspond to the IREAD, 
IREADC, IREADF, and IREADK modes. 



(continued on next page) 
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Table 0-1 (cont.) 
Summary of SYSLIB Subprograms 



Function 
Call 


Section 


Purpose 


Data Transf 


er Functions 


(cont. ) 


IREAD 


0.3.36 


Transfers data via the specified channel to a 
memory buffer and returns control to the user 
program when the transfer request is entered 
in the I/O queue. No special action is taken 
upon completion of I/O. 


IREADC 


0.3.36 


Transfers data via the specified channel to a 
memory buffer and returns control to the user 
program when the transfer request is entered 
in the I/O queue. Upon completion of the 
read, control transfers to the assembly 
language routine specified in the IREADC 
function call . 


IREADF 


0.3.36 


Transfers data via the specified channel to a 
memory buffer and returns control to the user 
program when the transfer request is entered 
in the I/O queue. Upon completion of the 
read, control transfers to the FORTRAN 
subroutine specified in the IREADF function 
call . 


IREADW 


0.3.36 


Transfers data via the specified channel to a 
memory buffer and returns control to the 
program only after the transfer is complete. 


*ISDAT 
*ISDATC 
*ISDATF 
*ISDATW 


0.3.41 


Allows the user to send messages or data to 
the other job in an F/B environment. The four 
modes correspond to the IWRITE, IWRITC, 
IWRITF, and IWRITW modes. 


ITTINR 


0.3.47 


Inputs one character from the console 
keyboard . 


ITTOUR 


0.3.48 


Transfers one character to the console 
terminal . 


IWAIT 


0.3.51 


Waits for completion of all I/O on a specified 
channel. (Commonly used with the IREAD and 
IWRITE functions.) 


IWRITC 


0.3.52 


Transfers data via the specified channel to a 
device and returns control to the user program 
when the transfer request is entered in the 
I/O queue. Upon completion of the write, 
control transfers to the assembly language 
routine specified in the IWRITC function call. 



(continued on next page) 
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Table 0-1 (cont.) 
Summary of SYSLIB Subprograms 



Function 


Section 


Purpose 


Call 






Data Transf 


er Functions 


(cont.) 


IWRITE 


0.3.52 


Transfers data via the specified channel to a 
device and returns control to the user program 
when the transfer request is entered in the 
I/O queue. No special action is taken upon 
completion of the I/O. 


IWRITF 


0.3.52 


Transfers data via the specified channel to a 
device and returns control to the user program 
when the transfer request is entered in the 
I/O queue. Upon completion of the write, 
control transfers to the FORTRAN subroutine 
specified in the IWRITF function call. 


IWRITW 


0.3.52 


Transfers data via the specified channel to a 
device and returns control to the user program 
only after the transfer is complete. 


*MWAIT 


0.3.68 


Waits for messages to be processed. 


PRINT 


0.3.69 


Outputs an ASCII string to the console 
terminal . 


Channel-Oriented Operations 


ICDFN 


0.3.14 


Defines additional I/O channels. 


*ICHCPY 


0.3.15 


Allows access to files currently open in the 
other job's environment. 


*ICSTAT 


0.3.18 


Returns the status of a specified channel. 


IFREEC 


0.3.24 


Returns the specified RT-11 channel to the 
available pool of channels for the FORTRAN I/O 
system. 


IGETC 


0.3.25 


Allocates an RT-11 channel and marks it in use 
to the FORTRAN I/O system. 


ILUN 


0.3.27 


Returns the RT-11 channel number with which a 
FORTRAN logical unit is associated. 


IREOPN 


0.3.38 


Restores the parameters stored via an ISAVES 
function and reopens the channel for I/O. 


ISAVES 


0.3.39 


Stores five words of channel status 
information into a user-specified array. 


PURGE 


0.3. 70 


Deactivates a channel . 



(continued on next page) 
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Table 0-1 (cont.) 
Summary of SYSLIB Subprograms 



Function 
Call 


Section 


Purpose 


Device and 


File Specifications 


IASIGN 


0.3.13 


Sets information in the FORTRAN logical unit 
table. 


ICSI 


0.3.17 


Calls the RT-11 CSI in special mode to decode 
file specifications and switches. 


Timer Suppo 


rt Operations 


CVTTIM 


0.3.5 


Converts a 2-word internal format time to 
hours, minutes, seconds, and ticks. 


GTIM 


0.3.9 


Gets time of day. 


*ICMKT 


0.3.16 


Cancels an unexpired ISCHED, ITIMER, or MRKT 
request. 


*ISCHED 


0.3. 40 


Schedules the specified FORTRAN subroutine to 
be entered at the specified time of day as an 
asynchronous completion routine. 


*ISLEEP 


0.3.42 


Suspends main program execution of the running 
job for a specified amount of time; 
completion routines continue to run. 


*ITIMER 


0.3.45 


Schedules the specified FORTRAN subroutine to 
be entered as an asynchronous completion 
routine when the time interval specified has 
elapsed . 


*ITWAIT 


0.3.49 


Suspends the running job for a specified 
amount of time; completion routines continue 
to run. 


*IUNTIL 


0.3. 50 


Suspends the main program execution of the 
running job until a specified time-of-day; 
completion routines continue to run. 


JTIME 


0.3.63 


Converts hours, minutes, seconds, and ticks 
into 2-word internal format time. 


*MRKT 


0.3.67 


Marks time, i.e., schedules an assembly 
language routine to be activated as an 
asynchronous completion routine after a 
specified interval. 



(continued on next page) 
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Table 0-1 (cont.) 
Summary of SYSLIB Subprograms 



Function 
Call 


Section 


Purpose 


Timer Support Operations (cont.) 


SECNDS 


0.3. 80 


Returns the current system time in seconds 
past midnight minus the value of a specified 
argument. 


TIMASC 


0.3.84 


Converts a specified 2-word internal format 
time into an 8-character ASCII string. 


TIME 


0.3.85 


Returns the current system time-of-day as an 
8-character ASCII string. 


RT-11 Servi 


ces 




CHAIN 


0.3.2 


Chains to another program (in the background 
job only) . 


*DEVICE 


0.3.6 


Specifies actions to be taken on normal or 
abnormal program termination, such as turning 
off interrupt enable on foreign devices, etc. 


GTJB 


0.3. 10 


Returns the parameters of this job. 


IDS TAT 


0.3.21 


Returns the status of the specified device. 


IFETCH 


0.3.23 


Loads a device handler into memory. 


IQSET 


0.3.33 


Expands the size of the RT-11 monitor queue 
from the free space managed by the FORTRAN 
system. 


ISPFN 
ISPFNC 
ISPFNF 
ISPFNW 


0.3.43 


Issues special function requests to various 
handlers, e.g., magtape. The four modes 
correspond to the IWRITE, IWRITC, IWRITF, and 
IWRITW modes. 


*ITL0CK 


0.3.46 


Indicates whether the USR is currently in use 
by another job and performs a LOCK if the USR 
is available. 


LOCK 


0.3.65 


Makes the RT-11 monitor User Service Routine 
(USR) permanently resident until an UNLOCK 
function is executed. A portion of the user's 
program is swapped out to make room for the 
USR if necessary. 


RCHAIN 


0.3.74 


Allows a program to access variables passed 
across a chain. 



(continued on next page) 
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Table 0-1 (cont.) 
Summary of SYSLIB Subprograms 



Function 
Call 


Section 


Purpose 


RT-11 Services (cont.) 




RCTRLO 


0.3.75 


Enables output to the terminal by cancelling 
the effect of a previously typed CTRL 0, ii: 
any. 


*RESUME 


0.3.77 


Causes the main program execution of a job to 
resume where it was suspended by a SUSPNI) 
function call. 


*SUSPND 


0.3.83 


Suspends main program execution of: the running 
job; completion routines continue to execute,, 


UNLOCK 


0.3.88 


Releases the USR if a LOCK was performed; the 
user program is swapped in if required. 


INTEGER*4 S 


upport Funct 


ions 


AJFLT 


0.3.1 


Converts a specified INTEGER*4 value to REAL*4 
and returns the result as the function value. 


DJFLT 


0.3.7 


Converts a specified INTEGER*4 value to REAL*8 
and returns the result as the function value. 


IAJFLT 


0.3.12 


Converts a specified INTEGER*4 value to REAL*4 
and stores the result. 


IDJFLT 


0.3. 20 


Converts a specified INTEGER*4 value to REAL* 8 
and stores the result. 


IJCVT 


0.3.26 


Converts a specified INTEGER*4 value to 
INTEGER*2. 


JADD 


0.3.53 


Computes the sum of two INTEGER*4 values. 


JAFIX 


0.3.54 


Converts a REAL*4 value to INTEGER*4. 


JCMP 


0.3.55 


Compares two INTEGERM values and returns an 
INTEGER*2 value that reflects the signed 
comparison result. 


JDFIX 


0.3.56 


Converts a REAL*8 value to INTEGER*4. 


JDIV 


0.3.57 


Computes the quotient and remainder of two 
INTEGER*4 values. 


JICVT 


0.3.58 


Converts an INTEGER*2 value to INTEGER*4. 



(continued on next page) 
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Table 0-1 (cont.) 
Summary of SYSLIB Subprograms 



Function 
Call 



Section 



Purpose 



INTEGER*4 Support Functions (cont.) 



JJCVT 

JMOV 
JMUL 
JSUB 



0.3.59 

0.3. 60 
0.3.61 
0.3.62 



Converts 2-word internal time 
INTEGER*4 format, and vice versa. 



format 



to 



Assigns an INTEGER*4 value to a variable. 

Computes the product of two INTEGER*4 values. 

Computes the difference between two INTEGER*4 
values. 



Character String Functions 



CONCAT 
GETSTR 

INDEX 

INSERT 

ISCOMP 
IVERIF 

LEN 

PUTSTR 

REPEAT 



SCOMP 


0.3.78 


SCOPY 


0.3.79 


STRPAD 


0.3.81 



0.3.4 
0.3.8 

0.3.28 
0.3.29 

0.3.78 

0.3.89 

0.3.64 
0.3.71 
0.3.76 



Concatenates two variable-length strings. 

Reads a character string from a specified 
FORTRAN logical unit. 



Returns the location in one string of the 
first occurrence of another string . 

Replaces a portion of one string with another 
string . 

Compares two character strings. 

Indicates whether characters in one string 
appear in another. 

Returns the number of characters in a 
specified string. 

Writes a variable-length character string on a 
specified FORTRAN logical unit. 

Concatenates a specified string with itself to 
provide an indicated number of copies and 
stores the resultant string. 

Compares two character strings. 

Copies a character string from one array to 
another . 

Pads a variable-length string on the right 
with blanks to create a new string of a 
specified length. 



(concluded on next page) 
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Table 0-1 (cont.) 
Summary of SYSLIB Subprograms 



Function 
Call 


Section 


Purpose 


Character String Functions (cont.) 


SUBSTR 


0.3.82 


Copies a substring from a specified string. 


TRANS L 


0.3.86 


Replaces one string with another after 
performing character modification. 


TRIM 


0.3.87 


Removes trailing blanks from a character 
string . 


VERIFY 


0.3.89 


Indicates whether characters in one string 
appear in another. 


Radix-50 Co 


nversion Ope 


rations 


IRAD50 


0.3.34 


Converts ASCII characters to Radix-50, 
returning the number of characters converted. 


R50ASC 


0.3.72 


Converts Radix-50 characters to ASCII. 


RAD50 


0.3.73 


Converts six ASCII characters, returning a 
REAL*4 result which is the 2-word Radix-50 
value . 


Miscellaneo 


us Services 




IADDR 


0.3.11 


Obtains the memory address of a specified 
entity. 


INTSET 


O.3.30 


Establishes a specified FORTRAN subroutine as 
an interrupt service routine at a specified 
priority. 


IPEEK 


0.3.31 


Returns the value of a word located at a 
specified absolute memory address. 


IPOKE 


0.3.32 


Stores an integer value in an absolute memory 
location. 


ISPY 


0.3.44 


Returns the integer value of the word located 
at a specified offset from the beginning of 
the RT-11 resident monitor. 



Routines requiring the USR (see Section 9.2.5) differ between the 
Single-Job and F/B Monitors. The following functions require the use 
of the USR: 

CLOSEC 

GETSTR (only if first I/O operation on logical unit) 

ICDFN (Single-Job only) 
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ICSI 

IDELET 

IDS TAT 

IENTER 

IFETCH 

IQSET 

IRENAM 

ITLOCK (only if USR is not in use by the other job) 

LOCK (only if USR is in a swapping state) 

LOOKUP 

PUTSTR (only if first I/O operation on logical unit) 

Certain requests require a queue element taken from the same list as 
the I/O queue elements. These are: 

IRCVD/IRCVDC/IRCVDF/IRCVDW 

IREAD/IREADC/IREADF/IREADW 

ISCHED 

ISDAT/ISDATC/ISDATF/ISDATW 

ISLEEP 

ISPFN/ISPFNC/ISPFNF/ISPFNW 

ITIMER 

ITWAIT 

IUNTIL 

IWRITC/IWRITE/IWRITF/IWRITW 

MRKT 

MWAIT 



0.2.1 Completion Routines 

Completion routines are subprograms that execute asynchronously with a 
main program. A completion routine is scheduled to run as soon as 
possible after the event for which it has been waiting has completed 
(e.g., the completion of an I/O transfer, or the lapsing of a 
specified time interval) . All completion routines of the current job 
have higher priority than other parts of the job; therefore, once a 
completion routine becomes runnable because of its associated event, 
it interrupts execution of the job and continues to execute until it 
relinquishes control. 

Completion routines are handled differently in the Single-Job and the 
F/B versions of RT-11. In the Single-Job version, completion routines 
are totally asynchronous and can interrupt one another. In F/B, 
completion routines do not interrupt each other but are queued and 
made to wait until the correct job is running. (For further 
information on completion routines, see Sections 9.2.8 and 0.1.4.) 

A FORTRAN completion routine can have a maximum of two arguments: 

SUBROUTINE crtn { ( iargl , iarg2) } 

where: iargl is equivalent to RO on entry to an assembly 

language completion routine. 

iarg2 is equivalent to Rl on entry to an assembly 
language completion routine. 

If an error occurs in a completion routine or in a subroutine at 
completion level, the error handler will trace back normally through 
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to the original interruption of the main program. Thus the traceback 
is shown as though the completion routine were called from the main 
program and lets the user know where the main program was executing if 
a fatal error occurs. 

Certain restrictions apply to completion routines, i.e., those 
routines that are activated by the following calls:" 

INTSET 
IRCVDC 
IRCVDF 
IREADC 
IREADF 
ISCHED 
ISDATC 
ISDATF 
ISPFNC 
ISPFNF 
ITIMER 
IWRITC 
IWRITF 
MRKT 

These restrictions are: 

1. The first subroutine call that references a FORTRAN 
completion routine must be issued from the main program. 

2. No channels may be allocated (by calls to IGETC) or freed (by 
calls to IFREEC) from a completion routine. Channels to be 
used by completion routines should be allocated and placed in 
a COMMON block for use by the routine. 

3. The completion routine may not perform any call which 
requires the use of the USR, e.g., LOOKUP and IENTER. See 
Section 0.2 for a list of SYSLIB functions that call the USR. 

4. Files to be operated upon in completion routines must be 
opened and closed by the main program. There are, however,, 
no restrictions on the input or output operations that may be 
performed in the completion routine. If many files must be 
made available to the completion routine, they may be opened 
by the main program and saved for later use (without tying up 
RT-11 channels) by the ISAVES call. The completion routine 
may later make them available by reattaching the file to a 
channel with an IREOPN call. 

5. FORTRAN subprograms are reusable but not reentrant. A given 
subprogram can be used many times as a completion routine or 
as a routine in the main program but a subprogram executing 
as main program code will not work properly if interrupted at 
the completion level. This restriction applies to all 
subprograms that can be invoked at the completion level and 
can be active at the same time in the main program. 

6. Only one completion function should be active at any time 
under the Single-Job Monitor (see Section 0.1.4). 

7. Assembly language completion routines must be exited via an 
RTS PC. 
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FORTRAN completion routines must be exited by execution of 
RETURN or END statement in the subroutine. 



0.2.2 Channel-Oriented Operations 

An RT-11 channel being used for input/output with SYSLIB must be 
allocated in one of the following two ways: 

1. The channel is allocated and marked in use to the FORTRAN I/O 
system by a call to IGETC and is later freed by a call to 
IFREEC. 

2. An ICDFN call is issued to define more channels (up to 256) . 
All channels numbered greater than 17 (octal) can be freely 
used by the programmer; the FORTRAN I/O system uses only 
channels through 17 (octal) . 

Channels must be allocated in the main program routine or its 
subprograms, not in routines that are activated as the result of I/O 
completion events or ISCHED or ITIMER calls. 



0.2.3 INTEGER*4 Support Functions 

INTEGER*4 variables are allocated two words of storage. INTEGER*4 
values are stored in two's complement representation. The first word 
(lower address) contains the low-order part of the value, and the 
second word (higher address) contains the sign and the high-order part 
of the value. The range of numbers supported is -2 31 +1 to 2 31 -1. 

Note that this format differs from the 2-word internal time format 
which stores the high-order part of the value in the first word and 
the low-order part in the second. The JJCVT function (Section 0.3.59) 
is provided for conversion between the two internal formats. 

Integer and real arguments to subprograms are indicated in the 
following manner in this appendix. 

i = INTEGER*2 arguments 
j = INTEGER*4 arguments 
a = REAL*4 arguments 
d = REAL*8 arguments 

When the DATA statement is used to initialize INTEGER*4 variables, it 
must specify both the low- and high-order parts, i.e. 



• / 



INTEGER*4 J 
DATA J/3/ 

only initializes the first word. 

The correct way to initialize an INTEGER*4 variable to a constant 
(e.g., 3) is shown below: 

INTEGER*4 J 

INTEGER*2 1(2) 

EQUIVALENCE (J, I) 

DATA 1/3,0/ "INITIALIZE J TO 3 



0-17 



System Subroutine Library 

If initializing an INTEGER*4 variable to a negative value (e.g., -4), 
the high-order (second word) part must be the continuation of the 
two's complement of the low-order part. For example: 

INTEGER*4 J 

INTEGER*2 1(2) 

EQUIVALENCE (J, I) 

DATA I/-4,-l/ "INITIALIZE J TO -4 



The following form is suitable for INTEGER*4 arguments to subprograms: 

INTEGER*2 J (2) 

DATA J/3,0/ 'LOW-ORDER, HIGH -ORDER 



0.2.4 Character String Functions 

The SYSLIB character string functions and- routines provide 
variable-length string support for RT-11 FORTRAN. SYSLIB calls are 
provided to perform the following character string operations: 

• Read character strings from a specified FORTRAN logical unit 
(GETSTR) . 

• Write character strings to a specified FORTRAN logical unit, 
(PUTSTR) . 

• Concatenate variable-length strings (CONCAT) . 

• Return the position of one string in another (INDEX) . 

• Insert one string into another (INSERT) . 

• Return the length of a string (LEN) . 

• Repeat a character string (REPEAT). 

• Compare two strings (SCOMP) . 

• Copy a character string (SCOPY) . 

• Pad a string with rightmost blanks (STRPAD) . 

• Copy a substring from a string (SUBSTR) . 

• Perform character modification (TRANSL) . 

• Remove trailing blanks (TRIM) . 

• Verify the presence of characters in a string (VERIFY). 

Strings are stored in L0GICAL*1 arrays which are defined and. 
dimensioned by the FORTRAN programmer. Strings are stored in these 
arrays as one character per array element plus a zero element to 
indicate the current end of the string (ASCIZ format). 

The length of a string may vary at execution time, ranging from zero 
characters in length to one less than the size of the array which 
stores the string. The maximum size of any string is 32767 
characters. Strings may contain any of the 7-bit ASCII characters 
except null (0) , as the null character is used to mark the end of the 
string. Bit 7 of each character must be off (0); therefore, the 
valid characters are those whose decimal representations range from 1 
to 127, inclusive. 

The ASCII code used in this string package is the same as that 
employed by FORTRAN for A-type FORMAT items, ENCODE/DECODE strings, 
and object-time FORMAT strings. ASCIZ strings in the form used by 
these routines are generated by the FORTRAN compiler whenever quoted 
strings are used as arguments in the CALL statement. Note that a null 
string (a string containing no characters) may be represented in 
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FORTRAN by a variable or constant of any type which contains the value 
zero, or by a LOGICAL variable or constant with the .FALSE. value. 

The SYSLIB user should ensure that a string never overflows the array 
that contains it by being aware of the length of the string result 
produced by each routine. In many routines where the result string 
length may vary or is difficult to determine, an optional integer 
argument may be specified to the subroutine to limit the length. In 
the sections describing the character string routines, this argument 
is called "len". The length of an output string is limited 
to the value specified for "len" plus one (for the null terminator) ; 
therefore the array receiving the result must be at least "len" plus 
one elements in size. 

The optional argument "err" may be included when "len" is specified. 
"Err" is a logical variable which should be initialized by the FORTRAN 
program to the .FALSE, value. If a string function is given the 
arguments "len" and "err", and "len" is actually used to limit the 
length of the string result, then "err" is set to the .TRUE. value. 
If "len" is not used to truncate the string, "err" is unchanged, i.e., 
remains .FALSE. . 

"Len" and "err" are always optional arguments. "Len" may appear 
alone; however, "len" must appear if "err" is specified. 



s 



Several routines use the concept of character position. Each 

character in a string is assigned a position number which is one 

greater than the position of the character immediately to its left. 
The first character in a string is in position one. 



0.2.4.1 Allocating Character String Variables — A 1-dimensional 
L0GICAL*1 array may be used to contain a single string whose length 
may vary from zero characters to one less than the dimensioned length 
of the array. For example: 

L0GICAL*1 A(45) "ALLOCATE SPACE FOR STRING VARIABLE A 

The preceding example allows array A to be used as a string variable 
that can contain a string of 44 or less characters. Similarly, a 
2-dimensional L0GICAL*1 array may be used to contain a 1-dimensional 
array of strings. Each string in the array may have a length up to 
one less than the first dimension of the the L0GICAL*1 array. There 
may be as many strings as the number specified for the second 
dimension of the L0GICAL*1 array, e.g., 

L0GICAL*1 W(21,10) ! ALLOCATE AN ARRAY OF STRINGS 

The preceding example creates a string array W which has 10 string 
elements, each of which may contain up to 20 characters. String I in 
array W is referenced in subroutine or function calls as W(1,I). 

A 2-dimensional string array may be allocated, e.g., 

LOGICAL*l T(14,5,7) IALLOCATE A 5 BY 7 STRING ARRAY 

In the preceding example, each string in array T may vary in length to 
a maximum of 13 characters. String I, J of the array may be referenced 
as T(1,I,J). Note that T is the same as T(l,l,l). This dimensioning 
process may be continued to create string arrays of up to six 
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dimensions (represented by LOGICAL*l arrays of up to seven 
dimensions) . 



0.2.4.2 Passing Strings to Subprograms — The L0GICAL*1 arrays which 
contain strings may be placed in a COMMON block and referenced by any 
or all routines with a similar COMMON declaration. However, care 
should be taken when a L0GICAL*1 array is placed in a COMMON block, 
for if such an array has an odd length, it may cause all succeeding 
variables in the COMMON block to be assigned odd addresses. This 
situation will be detected by the RT-11 FORTRAN compiler, resulting in 
a warning message if the /W switch is specified. 

A L0GICAL*1 array has an odd length only if the product of its 
dimensions is odd, e.g., 

L0GICAL*1 B(10,7) !(10*7)=70; EVEN LENGTH 
L0GICAL*1 H(21) !21 IS ODD; ODD LENGTH 

If odd length arrays are to be placed in a COMMON block, they should 
either be placed at the end of the block or they should be paired to 
result in an effective even length. For example: 

COMMON A1,A2,A3(10) ,H(21) 1PLACE ODD-SIZED ARRAY AT END 

or 

COMMON A1,A2,H(21) ,H1(7) ,A3(10) !PAIR ODD-SIZED ARRAYS H AND HI 

Note that these cautions apply only to L0GICAL*1 variables and arrays. 

The second method of passing strings to subprograms is through 
arguments and formal parameters. A single string may be passed by 
using its array name as an argument. For example: 

L0GICAL*1 A(21) 1STRING VARIABLE "A", 20 CHARACTERS MAXIMUM 
CALL SUBR(A) IPASS STRING A TO SUBROUTINE SUBR 

If the maximum length of a string argument is unknown in a subroutine 
or function, or if the routine is used to handle many different length 
strings, the dummy argument in the routine should be declared as a 
L0GICAL*1 array with a dimension of one, e.g., LOGICAL*l ARG(l). In 
this case, the string routines will correctly determine the length of 
ARG whenever it is used, but it will not be possible to determine the 
maximum size string which may be stored in ARG. If a 
multi-dimensional array of strings is passed to a routine, it must be 
declared in the called program with the same dimensions as were 
specified in the calling program. 

NOTE 

The length argument specified in many of 
the character string functions refers to 
the maximum length of the string 
excluding the necessary null byte 
terminator. The length of the L0GICAL*1 
array to receive the string must be at 
least one greater than the length 
argument. 
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0.2.4.3 Using Quoted-Str ing Literals — Quoted-str ings may be used as 
arguments to any of the string routines that are invoked by the CALL 
statement. They cannot be used for routines invoked as functions. 
For example: 

CALL SCOMP (NAME, 'DOE, J0HN',M) 

compares the string in the array NAME to the constant string DOE, JOHN 
and sets the value of the integer variable M accordingly. Although 
the above form of the routine reference is permitted, the statement: 

M=ISC0MP (NAME, "DOE, JOHN') 

is not allowed since the routine is not invoked by the CALL statement 
and includes a quoted-str ing literal. 



0.3 LIBRARY FUNCTIONS AND SUBROUTINES 

This section presents all SYSLIB functions and subroutines in 
alphabetic order. To reference these subprograms by usage, see Table 
0-1. 



AJFLT 



0.3.1 AJFLT 

The AJFLT function converts an INTEGER*4 value to a REAL*4 value and 
returns that result as the function value. 

Form: a = AJFLT (jsrc) 

where: jsrc is the INTEGERM variable to be converted. 

Function Results: 

The function result is the REAL*4 value that is the result of the 
operation. 

Example: 

The following example converts the INTEGER*4 value contained in JVAL 
to single precision (REAL*4) , multiplies it by 3.5, and stores the 
result in VALUE. 

REAL*4 VALUE, AJFLT 
INTEGER*4 JVAL 



VALUE=AJFLT (JVAL) *3 . 5 
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CHAIN 



0.3.2 CHAIN 

The CHAIN subroutine allows a background program (or any program in 
the Single-Job system) to transfer control directly to another 
background program, passing it specified information. CHAIN cannot 
be called from a completion or interrupt routine. CHAIN does not 
close any of the FORTRAN logical units. When CHAINing to any other 
program, the user should explicitly close the opened logical units 
with calls to the CLOSE routine. Any USEREX routine specified to 
the FORTRAN run-time system will not be executed if a CHAIN is 
accomplished. 

Form: CALL CHAIN (dblk, var ,wcnt) 



where : dblk 



is the address of a 4-word Radix-50 
descriptor of the file specification for 
the program to be run. (See the FORTRAN 
Language Reference Manual, Section 2.2.8.) 



var is the first variable in a sequence of 
variables with increasing memory addresses to 
be passed between programs in the chain 
parameter area (absolute locations 510 up to 
700) . A single array or a COMMON block (or 
portion of a COMMON block) is a suitable 
sequence of variables. 

went is a word count (up to 60 words) specifying 
the number of words (beginning at var) to be 
passed to the called program. 

If the size of the chain parameter area is insufficient, it may be 
increased by specifying the /B (bottom) switch to LINK for both the 
program executing the CHAIN call and the program receiving control . 

The data passed may be accessed through a call to the RCHAIN routine 
(see Section 0.3.74). For more information on chaining to other 
programs, see Section 9.4.2. 

Errors: 

None. 
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Example: 

The following example transfers control from the main program to 
PROG.SAV, on DTO, passing it variables. 



REAL* 4 PROGNM 

COMMON /BLK1/ A,B,C,D 

DATA PROGNM/ 6 RDT0PRO,6RG SAV/ 



1RAD50 FOR PROGRAM NAME 
IDATA TO BE PASSED 



CALL CHAIN (PROGNM, A, 8) 



!RUN DTO: PROG. SAV 



CLOSEC 



0.3.3 CLOSEC 

The CLOSEC subroutine terminates activity on the specified channel and 
frees it for use in another operation. The handler for the associated 
device must be in memory. CLOSEC cannot be called from a completion 
or interrupt routine. 

Form: CALL CLOSEC (chan) 

where: chan is the channel number to be closed. This 

argument must be located so that the USR 
cannot swap over it. 

A CLOSEC or PURGE must eventually be issued for any channel opened for 
either input or output. A CLOSEC call specifying a channel that is 
not open is ignored. 

A CLOSEC performed on a file that was opened via an IENTER causes the 
device directory to be updated to make that file permanent. If the 
device associated with the specified channel already contains a file 
with the same name and extension, the old copy is deleted when the new 
file is made permanent. A CLOSEC on a file opened via LOOKUP does not 
require any directory operations. 

When an entered file is CLOSECed, its permanent length reflects the 
highest block of the file written since the file was entered; for 
example, if the highest block written is block number 0, the file is 
given a length of 1; if the file was never written, it is given a 
length of 0. If this length is less than the size of the area which 
was allocated at IENTER time, the unused blocks are reclaimed as an 
empty area on the device. 



Errors : 

CLOSEC does not generate any errors. If the device handler for 
operation is not in memory, a fatal monitor error is generated. 



the 
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Example : 

The following example creates and processes a 56-block file, 

REAL*4 DBLK(2) 

DATA DBLK/6RSY0NEW,6RFILDAT/ 

DATA ISIZE/56/ 



ICHAN=IGETC() 
IF(ICHAN.LT.O) GOTO 100 

IF(IENTER(ICHAN,DBLK,ISIZE)-1) 10,110,120 
10 



CALL CLOSEC(ICHAN) 

CALL IFREEC(ICHAN) 

CALL EXIT 
100 STOP 'NO AVAILABLE CHANNELS' 
110 STOP 'CHANNEL ALREADY IN USE' 
120 STOP 'NOT ENOUGH ROOM ON DEVICE 1 

END 



CONCAT 



0.3.4 CONCAT 

The CONCAT subroutine is used to concatenate character strings. 

Form: CALL CONCAT (a ,b ,out{ ,len{ ,er r } }) 

where: a is the array containing the left string. 

b is the array containing the right string. 

out is the array into which the concatenated 
result is placed. This array must be at 
least one element longer than the maximum 
length of the result string (i.e., one 
greater than the value of len, if specified). 

len is the integer number of characters 
representing the maximum length of the output 
string. The effect of len is to truncate the 
output string to a given length, if 
necessary. 

err is the Logical error flag set if the output 
string is truncated to the length specified 
by len. 
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The string in array "a" immediately followed on the right by the 
string in array "b" and a terminating null character replaces the 
string in array "out". Any combination of string arguments is allowed 
so long as "b" and "out" do not specify the same array. Concatenation 
stops either when a null character is detected in "b" or when the 
number of characters specified by "len" have been moved. 

If either the left or right string is a null string, the other string 
is copied to "out". If both are null strings, then "out" is set to a 
null string. The old contents of "out" are lost when this routine is 
called . 

Errors : 

Error conditions are indicated by "err", if specified. If "err" is 

given and the output string would have been longer than "len" 

characters, then "err" is set to .TRUE.; otherwise, "err" is 
unchanged . 

Example: 

The following example concatenates the string in array STR and the 
string in array IN and stores the resultant string in array OUT. OUT 
cannot be larger than 29 characters. 

LOGICAL*! IN(30) ,OUT(30) ,STR(7) 



CALL CONCAT(STR,IN,OUT,29) 



CVTTIM 



0.3.5 CVTTIM 

The CVTTIM subroutine converts a 2-word internal format time to hours, 
minutes, seconds, and ticks. 

Form: CALL CVTTIM ( time ,hrs ,min , sec , tick) 

where: time is the 2-word internal format time to be 

converted. If time is considered as a 
2-element INTEGER*2 array, then: 

time (1) is the high-order time, 
time (2) is the low-order time. 

hrs is the integer number of hours. 
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min is the integer number of minutes. 

sec is the integer number of seconds. 

tick is the integer number of ticks (1/60 of a 
second for 60-cycle clocks; 1/50 of a second 
for 50-cycle clocks) . 



Errors : 

None. 

Example: 

INTEGER*4 ITIME 



CALL GTIM (ITIME) !GET CURRENT TIME-OF-DAY 

CALL CVTTIM (ITIME , IHRS , IMIN , ISEC , ITCK) 
IF(IHRS.GE.12) GOTO 100 'TIME FOR LUNCH 



DEVICE 



0.3.6 DEVICE (F/B only) 

The DEVICE subroutine allows the user to set up a list of addresses to 
be loaded with specified values when the program is terminated. If a 
job terminates or is aborted with a CTRL C from the terminal, this 
list is picked up by the system and the appropriate addresses are set 
up with the corresponding values. 

This function is primarily designed to allow user programs to load 
device registers with necessary values. In particular, it is used to 
turn off a device's interrupt enable bit when the program servicing 
the device terminates. 

Only one address list may be active at any given time; hence, if 
multiple DEVICE calls are issued, only the last one has any effect. 
The list must not be modified by the FORTRAN program after the DEVICE 
call has been issued, and the list must not be located in an overlay 
or an area over which the USR will swap. 

Form: CALL DEVICE (ilist) 

where: ilist is an integer array containing address/value 

pairs, terminated by a zero word. On program 
termination, each value is moved to the 
corresponding address. 

For more information on loading values into device registers, see the 
assembly language .DEVICE request, Section 9.4.11. 
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Errors: 
None . 
Example: 



INTEGER*2 IDR11(3) 
DATA IDR11 (1)/"167770/ 
DATA IDR11 (2)/0/ 
DATA IDR11 (3)/0/ 
CALL DEVICE (IDR11) 



! DEVICE ARRAY SPEC 

IDR11 CSR ADDRESS (OCTAL) 

! VALUE TO CLEAR INTERRUPT ENABLE 

!AND END-OF-LIST FLAG 

!SET UP FOR ABORT 



DJFLT 



0.3.7 DJFLT 

The DJFLT function converts an INTEGER*4 value into a REAL*8 (DOUBLE 
PRECISION) value and returns that result as the function value. 



Form: d = DJFLT (jsrc) 
where: jsrc 

Notes : 



specifies the INTEGER*4 variable which is to 
be converted. 



If DJFLT is used, it must be explicitly defined (REAL*8 DJFLT) or 

implicitly defined (IMPLICIT REAL*8 (D) ) in the FORTRAN program. If 

this is not done, its type will be assumed as REAL*4 (single 
precision) . 

Function Results: 

The function result is the REAL*8 value that is the result of the 
operation. 



Example; 



INTEGER*4 JVAL 
REAL*8 DJFLT, D 



D=DJFLT(JVAL) 
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GETSTR 



0.3.8 GETSTR 

The GETSTR subroutine reads a formatted ASCII record from a specified 

FORTRAN logical unit into a specified array. The data is truncated 

(trailing blanks removed) and a null byte is inserted at the end to 
form a character string. 

GETSTR can be used in main program routines or in completion routines 

but cannot be used in both at the same time. If GETSTR is used in a 

completion routine, it cannot be the first I/O operation on the 
specified logical unit. 

Form: CALL GETSTR (lun ,out ,len{ ,er r } ) 

where: lun is the integer FORTRAN logical unit number of 

a formatted sequential file from which the 
string is to be read. 

out is the array which is to receive the string; 
this array must be one element longer than 
len . 

len is the integer number representing the 
maximum length of the string to be input. 

err is the Logical error flag that is set to 
.TRUE. if the string specified by "out" 
exceeds the value of "len" in length; err 
must be present if the input string can 
exceed "len". 

Errors : 

Error conditions are indicated by "err". If "err" is given and the 
output string was truncated to the length specified by "len", then 
"err" is set to .TRUE.; otherwise, "err" remains unchanged. 

Example: 

The following example reads a string of up to 80 characters from 
logical unit 5 into the array STRING. 

LOGICAL*! STRING (81 ), ERR 



CALL GETSTR (5, STRING, 80, ERR) 
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0.3.9 GTIM 

THE GTIM subroutine allows user programs to access the current time of 
day. The time is returned in two words and is given in terms of clock 
ticks past midnight. If the system does not have a line clock, a 
value of zero is returned. If an RT-11 monitor TIME command has not 
been entered, the value returned will be the time elapsed since the 
system was bootstrapped rather than the time of day. 

Form: CALL GTIM (itime) 

where: itime is the 2-word area to receive the time of day. 

The high-order time is returned in the first word, the low-order time 
in the second word. The SYSLIB routine CVTTIM (Section 0.3.5) can be 
used to convert the time into hours, minutes, seconds and ticks. 
CVTTIM performs the conversion based on the monitor configuration word 
for 50- or 60-cycle clocks (see Section 9.2.6). Under an F/B Monitor, 
the time-of-day is automatically reset after 24:00 when a GTIM is 
executed; under the Single-Job Monitor, it is not. 

Errors : 

None . 

Example : 

INTEGERM JTIME 



CALL GTIM (JTIME) 




0.3. 10 GTJB 

The GTJB subroutine passes certain job parameters back to the user 
program. 
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Form: CALL GTJB (addr) 
where: addr 



is an 8-word area to receive the job 
parameters. This area, considered as an 
8-element INTEGER*2 array, has the following 
format: 



addr (1) 

addr (2) 
addr (3) 
addr (4) 
addr (5)- 
addr (8) 



job number. (0=Background ,, 

2=Foreground) 

high memory limit 

low memory limit 

beginning of I/O channel space 

reserved for future use 



For more information on passing job parameters, see the assembly 
language .GTJB request, Section 9.4.17. 

Errors: 

None . 

Example : 

INTEGER*2 PARAMS(8) 
CALL GTJB(PARAMS) 
IF(PARAMS(1) .EQ.O) TYPE 99 
99 FORMAT (' THIS IS THE BACKGROUND JOB') 




0.3.11 IADDR 

The IADDR function returns the 16-bit absolute memory address of its 
argument as the integer function value. 



is the variable, constant, or expression 
whose memory address is to be obtained. 



Form: i = IADDR (arg) 
where: arg 

Errors: 

None . 

Example: 

IADDR can be used to find the address of an assembly language global 
area. For example: 

EXTERNAL CAREA 
J=IADDR(CAREA) 
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IAJFLT 



0.3.12 IAJFLT 

The IAJFLT function converts an INTEGER*4 value to a REAL*4 value and 
stores the result. 

Form: i = IAJFLT (jsrc,ares) 

where: jsrc is the INTEGER*4 variable to be converted. 

ares is the REAL*4 variable or array element to 
receive the converted value. 

Function Results: 

The function result indicates the following: 

i = -2 Significant digits were lost during the 
conversion . 

= -1 Normal return; the result is negative. 

= Normal return; the result is zero. 

= 1 Normal return; the result is positive. 



Example; 



INTEGER*4 JVAL 
REAL*4 RESULT 



IF (IAJFLT (JVAL, RESULT) .EQ. -2) TYPE 99 
99 FORMAT (' OVERFLOW IN INTEGER*4 TO REAL CONVERSION') 
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IASIGN 



0.3.13 IASIGN 

The IASIGN function sets information in the FORTRAN logical unit table 
(overriding the defaults) so that the specified information is used 
when the FORTRAN Object Time System (OTS) opens the logical unit. 
This function can be used with ICSI (see Section 0.3.17) to allow a 
FORTRAN program to accept a standard CSI input specification. IASIGN 
must be called before the unit is opened, i.e., before any READ, 
WRITE, PRINT, TYPE, or ACCEPT statements are executed that reference 
the logical unit. 

Form: i = IASIGN (lun ,idev{ ,if ilex{ ,isize{ ,itype} }}) 

where: lun is an INTEGER*2 variable, constant, or 

expression specifying the FORTRAN logical 
unit for which information is being 
specified . 

idev is a 1-word Radix-50 device name; this can 
be the first word of an ICSI input or output 
file specification. 

ifilex is a 3-word Radix-50 filename and extension; 
this can be words 2 through 4 of an ICSI 
input or output file specification. 

isize is the length (in number of blocks) to 
allocate for an output file; this can be the 
fifth word of an ICSI output specification. 
If zero, the larger of either one-half the 
largest empty segment or the entire second 
largest empty segement is allocated (see 
Section 9.4.13). If the value specified for 
length is -1 , the entire largest empty 
segment is allocated. 

itype is an integer value determining the optional 
attributes to be assigned to the file. This 
value is obtained by adding the values that 
correspond to the desired operations: 

1 use double buffering for output 

2 open the file as a temporary file 

4 perform a lookup on the file (otherwise,, 
the first FORTRAN I/O operation 
determines how the file is opened) 
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8 expand carriage control information (see 

Notes below) 
16 do not expand carriage control 

information 
32 file is read-only 



No te s : 



Expanded carriage control information applies only to formatted output 
files and means that the first character of each record is used as a 
carriage control character when processing a write operation to the 
given logical unit. The first character is removed from the record 
and converted to the appropriate ASCII characters to simulate the 
requested carriage control. 

If carriage control information is not expanded, the first character 
of each record is unmodified and the FORTRAN OTS outputs a line feed, 
followed by the record, followed by a carriage return. 

If carriage control is unspecified, the FORTRAN OTS sends expanded 
carriage control information to the terminal and line printer and 
sends unexpanded carriage control information to all other devices and 
files. See the PDP-11 FORTRAN Language Reference Manual, Section 6.3, 
for further carriage control information. 

Function Results: 

i = Normal return. 

<> The specified logical unit is already in use or 

there is no space for another logical unit 
association. 

Example: 

The following example creates an output file on logical unit 3 using 
the first output file given to the RT-11 command string interpreter 
(CSI) , sets it up for double buffering, creates an input file on 
logical unit 4 based on the first input file specification given to 
the RT-11 CSI, and makes it available for read-only access. 

INTEGER*2 SPEC (-39) 

REAL*4 EXT (2) 

DATA EXT/6RDATDAT,6RDATDAT/ ! DEFAULT EXTENSION IS DAT 



10 IF(ICSI (SPEC, EXT, ,,0) .NE.O) GOTO 10 

C 

C DO NOT ACCEPT ANY SWITCHES 



C 



CALL IASIGN(3,SPEC(1) ,SPEC(2) ,SPEC(5) ,1) 
CALL IASIGN(4,SPEC(16) ,SPEC(17) ,0,32) 
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0.3.14 ICDFN 

The ICDFN function increases the number of input/output channels. 
Note that ICDFN defines new channels; the previously-defined channels 
are not used. Thus, an ICDFN for 20 channels (while the 16 original 
channels are defined) causes only 20 I/O channels to exist; the space 
for the original 16 is unused. The space for the new channel area is 
allocated out of the free space managed by the FORTRAN system. 



Form: i = ICDFN (num) 
where: num 



Notes : 
1. 



is the integer number of channels to be 
allocated. The number of channels must be 
greater than 16 and can be a maximum of 256. 
SYSLIB can use all new channels greater than 
16 without a call to IGETC; the FORTRAN 
system input/output uses only the first 16 
channels. This argument must be positioned 
so that the USR cannot swap over it. 



ICDFN cannot be issued from a completion or interrupt 
routine . 



2. It is recommended that the ICDFN function be used at the 
beginning of the main program before any I/O operations are 
initiated . 

3. If ICDFN is executed more than once, a completely new set of 
channels is created each time ICDFN is called. 

4. ICDFN requires that extra memory space be allocated to 
foreground programs (see Section 0.1.4). 

Function Results: 



i = 
= 1 

= 2 



Normal return. 

An attempt was made to allocate fewer channels 

than already exist. 

Not enough free space is available for the channel 

area. 



Example: 



IF(ICDFN(24) .NE.O) STOP 'NOT ENOUGH MEMORY" 
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0.3.15 ICHCPY (F/B only) 

The ICHCPY function opens a channel for input, logically connecting it 
to a file which is currently open by another job for either input or 
output. This function may be used by either the foreground or the 
background. An ICHCPY must be done before the first read or write for 
the given channel. 

Form: i = ICHCPY (chan,ochan) 

where: chan is the channel which the job will use to read 

the data. 

ochan is the channel number of the other job which 
is to be copied. 



Notes : 



1. If the other job's channel was opened via an IENTER function 
or a .ENTER programmed request to create a file, the copier's 
channel indicates a file which extends to the highest block 
that the creator of the file had written at the time the 
ICHCPY was executed. 

2. A channel which is open on a sequential-access device | 
should not be copied, because buffer requests may become 
intermixed . 

3. A program can write to a file (which is being created by the 
other job) on a copied channel just as it could if it were 
the creator. When the copier's channel is closed, however, 
no directory update takes place. 



Errors : 



i = Normal return. 

= 1 Other job does not exist or does not have the 

specified channel (ochan) open. 
= 2 Channel (chan) is already open. 
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0.3.16 ICMKT (F/B only) 

The ICMKT function causes one or more scheduling requests (made by an 
ISCHED, ITIMER or MRKT routine) to be cancelled. 

Form: i = ICMKT (id, time) 

where: id is the identification integer of the request 

to be cancelled. If id is equal to zero, all 
scheduling requests are cancelled. 

time is the name of a 2-word area in which the 
monitor will return the amount of time 
remaining in the cancelled request. 

For further information on cancelling scheduling requests, see the 
assembly language .CMKT request, Section 9.4.5. 

Errors : 

i = Normal return. 

=1 id was not equal to zero and no schedule request 

with that identification could be found. 

Example: 

INTEGER*4 J 



CALL ICMKT (0, J) "ABORT ALL TIMER REQUESTS NOW 



END 
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0.3.17 ICSI 

The ICSI function calls the RT-11 command string interpreter in 
special mode to parse a command string and return file descriptors and 
switches to the program. In this mode, the CSI does not perform any 
handler fetches, CLOSES, ENTERS, or LOOKUPS. ICSI cannot be called 
from a completion or interrupt routine. 

Form: i = ICSI (f ilspc ,defext, {cstring} , {switch} ,x) 

where: f ilspc is the 39-word area to receive the file 

specifications. The format of this area 

(considered as a 39-element INTEGER*2 array) 
is: 

filspc(l)- output file number 1 

f ilspc (4) specification 

f ilspc (5) output file number 1 length 

f ilspc (6)- output file number 2 

f ilspc (9) specification 

f ilspc (10) output file number 2 length 

filspc(ll)- output file number 3 

f ilspc (14) specification 

f ilspc (15) output file number 3 length 

filspc(16)- input file number 1 
f ilspc (19) specification 

f ilspc (20)- input file number 2 
f ilspc (23) specification 

f ilspc (24)- input file number 3 
f ilspc (27) specification 

f ilspc (28)- input file number 4 
f ilspc (31) specification 

f ilspc (32)- input file number 5 
f ilspc (35) specification 

f ilspc (36)- input file number 6 
f ilspc (39) specification 

defext is the table of Radix-50 default extensions 
to be assumed when a file is specified 
without an extension. 
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defext(l) is the default for all input 

file extensions. 

defext(2) is the default extension for 

output file number 1. 

defext(3) is the default extension for 

output file number 2. 

defext(4) is the default extension for 

output file number 3. 

cstring is the area which contains the ASCIZ command 
string to be interpreted; the string must 
end in a zero byte. If this argument is 
omitted, the system prints the prompt 
character (*) at the terminal and accepts a 
command string. 

switch is the name of an INTEGER*2 array dimensioned 
(4,n) where n represents the number of 
switches which are defined to the program. 
This argument must be present if the value 
specified for "x" is non-zero. This array 
has the following format for the nth switch 
described by the array. 

switch (l,n) is the 1-character ASCII name 
of the switch. 

switch(2,n) is set by the routine to 0, if 
the switch did not occur; to 
1, if the switch occurred 
without a value; to 2 , if the 
switch occurred with a value. 

switch (3, n) is set to the file number on 
which the switch is specified. 

switch (4, n) is set to the specified value 
if switch(2,n) is equal to 2. 

x is the number of switches defined in the 
array "switch". 



Notes : 



The array "switch" must be set up to contain the names of the valid 
switches. For example, use the following to set up names for five 
switches : 

INTEGER*2 SW(4,5) 

DATA SW(l,l)/ , S , /rSW(l,2)/'M l //SW(l,3)/ , I'/ 

DATA SW(1,4)/'L'/,SVI(1,5)/'E'/ 

Multiple occurrences of the same switch are supported by allocating an 
entry in the switch array for each occurrence of the switch. Each 
time the switch occurs in the switch array, the next unused entry for 
the named switch will be used. 

The arguments of ICSI must be positioned so that the USR cannot swap 
over them. 

For more information on calling the Command String Interpreter, see 
the assembly language .CSISPC request, Section 9.4.8. 
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Errors: 

i = Normal return. 

= 1 Illegal command line; no data was returned. 

=2 An illegal device specification occurred in the 

string . 
=3 An illegal switch was specified, or a given switch 

was specified more times than allowed for in the 

switch array. 

Example: 

The following example causes the program to loop until a valid command 
is typed at the console terminal. 

INTEGER*2 SPEC (39) 

REAL*4 EXT (2) 

DATA EXT/6RDATDAT,6RDATDAT/ 



10 TYPE 99 

99 FORMAT (' ENTER VALID CSI STRING WITH NO SWITCHES') 
IF(ICSI (SPEC, EXT, ,,0) .NE.O) GOTO 10 



ICSTAT 



0.3.18 ICSTAT (F/B only) 

The ICSTAT function furnishes the user with information about a 
channel. It is supported only in the F/B environment; no information 
is returned when operating under the Single-Job Monitor. 

Form: i = ICSTAT (chan,addr) 

where: chan is the channel whose status is desired. 

addr is a 6-word area to receive the status 
information. The area, as a 6-element 
INTEGER*2 array, has the following format. 

addr(l) channel status word (see 
Section 9.4.34) 

addr (2) starting block number of file 
on this channel 

addr (3) length of file 

addr (4) highest block number written 
since file was opened (see 
Section 9.4.9) 
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addr(5) unit number of device with 
which this channel is 
associated 

addr(6) Radix-50 of device name with 
which the channel is associated 



Errors: 



i = Normal return. 

= 1 Channel specified is not open. 

Example : 

The following example obtains channel status information about channel 
I. 

INTEGER*2 AREA (6) 
1=7 

IF(ICSTAT(I,AREA) .NE.O) TYPE 99,1 
99 F0RMAT(1X, 'CHANNEL' ,14, 'IS NOT OPEN') 



IDELET 



0.3.19 IDELET 

The IDELET function deletes a named file from an indicated device. 
IDELET cannot be issued from a completion or interrupt routine. 

Form: i = IDELET (chan ,dblk{ , count }) 

where: chan is the channel to be used for the delete 

operation. 

dblk is the 4-word Radix-50 specification 
(dev:filnam.ext) for the file to be deleted. 

count is used by magtape/cassette only to prevent a 
rewind before the operation. (Refer to 
Appendix H for more information concerning 
th€! magtape and cassette handlers.) 

NOTE 

The arguments of IDELET must be 
located so that the USR cannot swap 
over them. 
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The specified channel is left inactive when the IDELET is complete. 
IDELET requires that the handler to be used be resident (via an IFETCH 
call) at the time the IDELET is issued. If it is not, a monitor error 
occurs. 

For further information on deleting files, see the assembly language 
.DELETE request, Section 9.4.10. 

Errors : 

i = Normal return. 

= 1 Channel specified is already open. 

= 2 File specified was not found. 

Example: 

The following example deletes a file named FTN5.DAT from SYO. 

REAL*4 FILNAM(2) 

DATA FILNAM/6RSY0FTN,6R5 DAT/ 



I=IGETC() 

IF(I.LT.O) STOP 'NO CHANNEL' 

CALL IDELET (I, FILNAM) 

CALL IFREEC(I) 



IDJFLT 



O.3.20 IDJFLT 

The IDJFLT function converts an INTEGER*4 value into a REAL*8 (DOUBLE 
PRECISION) value and stores the result. 

Form: i = IDJFLT (jsrc,dres) 

where: jsrc specifies the INTEGER*4 variable that is to 

be converted. 

dres specifies the REAL*8 (or DOUBLE PRECISION) 
variable to receive the converted value. 

Function Results: 

The function result indicates the following: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is zero. 

= 1 Normal return; the result is positive. 
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Example: 



INTEGER*4 JJ 
REAL* 8 DJ 



IF(IDJFLT(JJ,DJ) .LE.O) TYPE -99 
99 FORMAT (' VALUE IS NOT POSITIVE'; 



IDSTAT 



0.3.21 IDSTAT 

The IDSTAT function is used to obtain information about a particular 
device. IDSTAT cannot be issued from a completion or interrupt 
routine . 

Form: i = IDSTAT (devnam ,cblk) 

where: devnam is the Radix-50 device name. 

cblk is the 4-word area used to store the status 
information. The area, as a 4-element 
INTEGER*2 array, has the following format: 

cblk(l) device status word (see Section 
9.4.12) 

cblk(2) size of handler in bytes 

cblk (3) entry point of handler 
(non-zero implies that the 
handler is in memory) 

cblk (4) size of the device (in 256-word 
blocks) for block-replaceable 
devices; zero for sequential- 
access devices 



NOTE 

The arguments of IDSTAT must be 
positioned so that the USR cannot 
swap over them. 



IDSTAT looks for the device specified by devnam and, if found, returns 
four words of status in cblk. 



January 1976 
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Errors : 



i = 
= 1 



Normal return. 

Device not found in monitor tables, 



Example : 



The following example determines whether the line printer handler is 
in memory. If it is not, the program stops and prints a message to 
indicate that the handler must be loaded. 

REAL* 4 IDNAM 

INTEGER*2 CBLK(4) 

DATA IDNAM/3RLP / 

DATA CBLK/4*0/ 

CALL IDSTAT (IDNAM, CBLK) 

IF(CBLK(3) .EQ.O) STOP 'LOAD THE LP HANDLER AND RERUN' 



IENTER 



0.3.22 IENTER 

The IENTER function allocates space on the specified device and 
creates a tentative directory entry for the named file. If a file of 
the same name already exists on the specified device, it is not 
deleted until the tentative entry is made permanent by CLOSEC. The 
file is attached to the channel number specified. 

Form: i = IENTER (chan ,dblk ,length{ , count }) 

where: chan is the integer specification for the RT-11 

channel to be associated with the file. 

dblk is the 4-word Radix-50 descriptor of the file 
to be operated upon. 

length is the integer number of blocks to be 
allocated for the file. If zero, the larger 
of either one-half the largest empty segment 
or the entire second largest empty segment is 
allocated (see Section 9.4.13). If the value 
specified for length is -1 , the entire 
largest empty segment is allocated. 

count is used by magtape/cassette only to prevent a 
rewind before the operation (see Appendix H) . 
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Notes : 

1. IENTER cannot be issued from a completion or interrupt 
routine . 

2. IENTER requires that the appropriate device handler be in 
memory. 

3. The arguments of IENTER must be positioned so that the USR 
does not swap over them. 

For further information on creating tentative directory entries, see 
the assembly language .ENTER request, Section 9.4.13. 



Errors : 
i : 



-1 
-2 



Normal return; number of blocks actually 
allocated (n = for nonf ile-structured IENTER) . 
Channel (chan) is already in use. 

In a fixed -length request, no space greater than 
or equal to length was found. 



Example: 



The following example allocates a channel for file TEMP.TMP on YO. 
no channel is available, the program prints a message and halts. 

REAL*4 DBLK(2) 

DATA DBLK/6RSY0TEM,6RP TMP/ 

ICHAN=IGETC() 

IF(ICHAN.LT.O) STOP 'NO AVAILABLE CHANNEL' 



If 



C 

c 
c 



CREATE TEMPORARY WORK FILE 
IF(IENTER(ICHAN,DBLK,20) .LT.O) STOP ' ENTER FAILURE ' 



CALL PURGE (ICHAN) 
CALL IFREEC (ICHAN) 



I F ETCH 



0.3.23 IFETCH 

The IFETCH function loads a device handler into memory from the system 
device, making the device available for input/output operations. The 
handler is loaded into the free area managed by the FORTRAN system. 
Once the handler is loaded, it cannot be released and the memory in 
which it resides cannot be reclaimed. IFETCH cannot be issued from a 
completion or interrupt routine. 
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Form: i = IFETCH (devnam) 



where: devnam is the 1-word Radix-50 name of the device for 

which the handler is desired. This argument 
can be the first word of an ICSI input or 
output file specification. This argument 
must be positioned so that the USR cannot 
swap over it. 



For further information on loading device handlers into 
the assembly language .FETCH request, Section 9.4.15. 



memory, see 



Errors: 



Normal return. 

Device name specified does not exist. 

Not enough room exists to load the handler. 

No handler for the specified device exists on 

system device. 



the 



Example : 



The following example requests the DX1 handler to be loaded into 
memory; execution stops if the handler cannot be loaded. 

REAL* 4 IDNAM 
DATA IDNAM/3RDX1/ 



IF (IFETCH (IDNAM) .NE.O) STOP 'FATAL ERROR FETCHING HANDLER" 



IFREEC 



0.3.24 IFREEC 

The IFREEC function returns a specified RT-11 channel to the available 
pool of channels. Before IFREEC is called, the specified channel must 
be closed or deactivated with a CLOSEC (see Section 0.3.3) or a PURGE 
(see Section 0.3. 70) call. IFREEC cannot be called from a completion 
or interrupt routine. IFREEC calls must be issued only for channels 
that have been successfully allocated by IGETC calls; otherwise, 
unpredictable results will occur. 

Form: i = IFREEC (chan) 



where: chan is the integer number of the 

freed . 



channel to be 
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Errors : 



i = Normal return. 

= 1 Specified channel is not currently allocated, 

Example: 

See the example under IGETC, (Section 0.3.25). 




0.3.25 IGETC 

The IGETC function allocates an RT-11 channel (in the range 0-17 
octal) and marks it in use for the FORTRAN I/O system. IGETC cannot 
be issued from a completion or interrupt routine. 

Forms i = IGETC () 

Function Results: 

i = -1 No channels are available. 
= n Channel n has been allocated. 



Example: 



ICHAN=IGETC() "ALLOCATE CHANNEL 

IF(ICHAN.LT.O) STOP 'CANNOT ALLOCATE CHANNEL" 



CALL IFREEC(ICHAN) ! FREE IT WHEN THROUGH 



END 



0-46 



System Subroutine Library 




0.3.26 IJCVT 

The IJCVT function converts an INTEGERM value to INTEGER*2 format. 
If ires is not specified, the result returned is the INTEGER*2 value 
of jsrc. If ires is specified, the result is stored there. 

Form: i = IJCVT ( jsrc {, ires }) 

where: jsrc specifies the INTEGER*4 variable or array 

element whose value is to be converted. 

ires specifies the INTEGER*2 entity to receive the 
conversion result. 

Function results if ires is specified: 



i = -2 
= -1 
= 
= 1 



An overflow occurred during conversion, 
Normal return; the result is negative, 
Normal return; the result is zero. 
Normal return; the result is positive, 



Example ; 



INTEGER*4 JVAL 
INTEGER*2 IVAL 



IF (IJCVT (JVAL, IVAL) .EQ.-2) TYPE 99 
99 FORMAT (' NUMBER TOO LARGE IN IJCVT CONVERSION') 




0.3.27 ILUN 

The ILUN function returns the RT-11 channel number with which a 
FORTRAN logical unit is associated. 
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Form: i = ILUN (lun) 
where: lun 



Function Results: 

i = -1 

= -2 

= +n 



is an integer expression whose value is a 
FORTRAN logical unit number in the range 
1-99. 



Logical unit is not open. 

Logical unit is opened to console terminal. 

RT-11 channel number n is associated with lun. 



Example: 



PRINT 99 
99 FORMAT (' PRINT DEFAULTS TO LOGICAL UNIT 6, WHICH FURTHER DEFAULTS TO LP:*) 
LUNRT=ILUN(6) 1WHICH RT-11 CHANNEL IS RECEIVING I/O? 



INDEX 



0.3.28 INDEX 

The INDEX subroutine searches a string for the occurrence of another 
string and returns the character position of the first occurrence of 
that string. 

Form: CALL INDEX (a ,pattrn , {i } ,m) 

or 

m = INDEX (a,pattrn{ ,i}) 



where; 



Errors; 
None. 



a is the array containing the string to be 
searched . 

pattrn is the string being sought. 

i is the integer starting character position of 
the search in a. If i is omitted, a is 
searched beginning at the first character 
position . 

m is the integer result of the search; m 
equals the starting character position of 
pattrn in a, if found; otherwise it is zero. 



January 1976 
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Example: 

The following example searches the array STRING for the first 
occurrence of strings EFG and XYZ and searches the string ABCABCABC 
for the occurrence of string ABC after position 5. 



CALL SCOPY ( ' ABCDEFGHI ' , STRING) 
CALL INDEX (STRING, 'EFG 1 ,,M) 
CALL INDEX (STRING, 'XYZ' ,,N) 
CALL INDEX ( ' ABCABCABC ' , ' ABC ' , 5 , L) 



UNITIALIZE STRING 

!M=5 

1N=0 

1L=7 



INSERT 



0.3.29 INSERT 

The INSERT subroutine replaces a portion of one string with another 
string . 

Form: CALL INSERT .( in ,out , i{ ,m} ) 

where: in is the array containing the string being 

inserted . 

out is the array containing the string being 
modified. 

i is the integer specifying the character 
position in "out" at which the insertion 
begins. 

m is the integer maximum number of characters 
to be inserted. 

If the maximum number of characters (m) is not specified, all 
characters to the right of the specified character position (i) in the 
string being modified are replaced by the string being inserted. The 
insert string (in) and the string being modified (out) may be in the 
same array only if the maximum number of characters (m) is specified 
and is less than or equal to the difference between the position of 
the insert (i) and the maximum string length of the array. 

Errors : 



None . 
Example; 



CALL SCOPY (' ABCDEFGHIJ' , SI) 
CALL SCOPY (SI, S2) 
CALL INSERT('123 ' ,S1,6,3) 
CALL INSERT{'123' ,S2,4) 



UNITIALIZE STRING 1 
UNITIALIZE STRING 2 
!S1 = 'ABCDE123IJ' 
!S2 = ■ABC123' 
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0.3. 30 INTSET 

The INTSET function establishes a FORTRAN subroutine as an interrupt 
service routine, assigns it a priority, and attaches it to a vector. 
INTSET requires that extra memory be allocated to foreground programs 
that use it (see Section 0.1.4). 

Form: i = INTSET (vect ,pr i ,id ,crtn) 

where: vect is the integer specifying the address of the 

interrupt vector to which the subroutine is 
to be attached. 

pri is the integer specifying the actual priority 
level (4-7) at which the device interrupts. 

id is the identification integer to be passed as 
the single argument to the FORTRAN routine 
when an interrupt occurs. This allows a 
single crtn to be associated with several 
INTSET calls. 

crtn is a FORTRAN subroutine to be established as 
the interrupt routine. This name should be 
specified in an EXTERNAL statement in the 
FORTRAN program that calls INTSET. The 
subroutine has one argument: 

SUBROUTINE crtn (id) 
INTEGER id 

When the routine is entered, the value of the 
integer argument will be the value specified 
for id in the appropriate INTSET call. 



Notes i 



1. The "id" argument may be used to distinguish between 
interrupts from different vectors if the routine to be 
activated services multiple devices. 

2. When using INTSET in F/B, the SYSLIB call DEVICE must be used 
in almost all cases to prevent interrupts from interrupting 
beyond program termination. 

3. If the interrupt routine (crtn) has control for a period of 
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time longer than the time in which two more interrupts using 
the same vector occur, interrupt overrun is considered to 
have occurred. The error message: 

?SYSLIB- FATAL INTERRUPT OVERRUN 

is printed and the job is aborted. Tasks requiring very fast 
interrupt response may not be viable using FORTRAN as FORTRAN 
overhead lowers RT-ll's interrupt response rate. 

4. The interrupt routine (crtn) is actually run as a completion 
routine via use of the RT-11 .SYNCH request (Section 
9.3.1.4). The "pri" argument is used for the RT-11 . INTEN 
request (Section 9.3.1.2). 

5. A .PROTECT request is issued for the vector, but no attempt 
is made to report an error if the vector is already 
protected; furthermore, the vector will be taken over 
unconditionally. See Section 9.4.25 for more information. 

6. The FORTRAN interrupt service subroutine (crtn) cannot call 
the USR. 

7. INTSET cannot be called from a completion or interrupt 
routine . 

8. Interrupt enable should not be set on the associated device 
until the INTSET call has been successfully executed. 

Errors: 

i = Normal return. 

= 1 Invalid vector specification. 

= 2 Reserved for future use. 

=3 No space is available for the linkage setup. 

Example: 

EXTERNAL CLKSUB ! SUBR TO HANDLE KWll-P CLOCK 



I=INTSET("104,6,0,CLKSUB) 1ATTACH ROUTINE 
IF (I.NE.O) GOTO 100 "BRANCH IF ERROR 



END 

SUBROUTINE CLKSUB (ID) 



END 
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0.3.31 IPEEK 

The IPEEK function returns the contents of the word located at a 
specified absolute 16-bit memory address. This function may be used 
to examine device registers or any location in memory. 



Form: i = IPEEK (iaddr) 
where: iaddr 



is the integer specification of the absolute 
address to be examined. If this argument is 
not an even value, a trap will result. 



Function Result: 

The function result (i) is set to the value of the word examined. 

Example: 

ISWIT = IPEEK("177570) !GET VALUE OF CONSOLE SWITCHES 




0.3.32 IPOKE 

The IPOKE subroutine stores a specified 16-bit integer value into a 
specified absolute memory location. This subroutine may be used to 
store values in device registers. 

Form: CALL IPOKE (iaddr , ivalue) 

where: iaddr is the integer specification of the absolute 

address to be modified. If this argument is 
not an even value, a trap will result. 
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ivalue is the integer value to be stored in the 
given address (iaddr). 

Errors : 

None . 

Example: 

The following example displays the value of IVAL in the console 
display register. 

CALL IPOKE ("177570, IVAL) 

To set bit 12 in the JSW without zeroing any other bits in the JSW, 
use the following procedure. 

CALL IPOKE (" 44, " 10000. OR. IPEEKf" 44) ) 



IQSET 



0.3.33 IQSET 

The IQSET function is used to make the RT-11 queue larger (i.e., add 
available elements to the queue) . These elements are allocated out of 
the free space managed by the FORTRAN system. IQSET cannot be called 
from a completion or interrupt routine. 

Form: i = IQSET (qleng) 

where: qleng is the integer number of elements to be added 

to the queue. This argument must be 
positioned so that the USR does not swap over 
it. 

All RT-11 I/O transfers are done through a centralized queue 
management system. If I/O traffic is very heavy and not enough queue 
elements are available, the program issuing the I/O requests may be 
suspended until a queue element becomes available. In an F/B system, 
the other job runs while the first program waits for the element. 
When IQSET is used in a program to be run in the foreground, the FRUN 
command must be modified to allocate space for the queue elements (see 
Section 0.1.4). 

A general rule to follow is that each program should contain one more 
queue element than the total number of I/O and timer requests that 
will be active simultaneously. Timing functions such as ITWAIT and 
MRKT also cause elements to be used and must be considered when 
allocating queue elements for a program. Note that if synchronous I/O 
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is done (i.e. IREADW/IWRITW, etc.) and no timing functions are done, 
no additional queue elements need be allocated. See Section 0.2 for a 
list of SYSLIB calls that use queue elements. 

For further information on adding elements to the queue, see the 
assembly language .QSET request, Section 9.4.27. 

Function Results: 

i = Normal return. 

= 1 Not enough free space is available for the number 

of queue elements to be added; no allocation was 
made . 

Example : 

IF(IQSET(5) .NE.O) STOP 'NOT ENOUGH FREE SPACE FOR QUEUE ELEMENTS' 



IRAD50 



0.3.34 IRAD50 

The IRAD50 function converts a specified number of ASCII characters to 
Radix-50 and returns the number of characters converted. Conversion 
stops on the first non-Radix-50 character encountered in the input or 
when the specified number of ASCII characters have been converted. 

Form: n = IRAD50 (icnt , input , output) 

where: icnt is the number of ASCII characters to be 

converted . 

input is the area from which input characters are 
taken. 

output is the area into which Radix-50 words are 
stored . 

Three characters of text are packed into each word of output. The 
number of output words modified is computed by the expression (in 
integer words) : 

(icnt+2)/3 

Thus, if a count of 4 is specified, two words of output are written 
even if only a 1-character input string is given as an argument. 
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Function Results: 



The integer number of input characters actually converted (n) is 
returned as the function result. 



Example : 



REAL*8 FSPEC 

CALL IRAD50 (12, 'SYOTEMP DAT 1 , FSPEC) 



IRCVD/IRCVDC/IRCVDF/IRCVDW 



0.3.35 IRCVD/IRCVDC/IRCVDF/IRCVDW (F/B only) 

There are four forms of the receive data function; these are used in 
conjunction with the ISDAT (send data) functions to' allow a general 
data/message transfer system. The receive data functions issue RT-11 
receive data programmed requests (see Section 9.4.29). These 
functions require a queue element; this should be considered when the 
IQSET function (Section 0.3.33) is executed. 

IRCVD 

The IRCVD function is used to receive data and continue execution. 
The operation is queued and the issuing job continues execution. At 
some point when the job must receive the transmitted message, an MWAIT 
should be executed. This causes the job to be suspended until the 
message has been received. 

Form: i = IRCVD (buff, went) 

where: buff is the array to be used to buffer the data 

received. The array must be one word larger 
than the message to be received because the 
first word will contain the integer number of 
words actually transmitted when IRCVD is 
complete . 

went is the maximum integer number of words that 
can be received. 



Errors : 



i = Normal return. 

=1 No foreground job exists in the system. 
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Example: 

INTEGER*2 MSG(41) 

CALL IRCVD(MSG,40) 

CALL MWAIT 



IRCVDC 

The IRCVDC function receives data and enters an assembly language 
completion routine when the message is received. The IRCVDC is queued 
and program execution stays with the issuing job. When the other job 
sends a message, the completion routine specified is entered. 

Form: i = IRCVDC (buf f ,wcnt ,,crtn) 

where: buff is the array to be used to buffer the data 

received. The array must be one word larger 
than the message to be received because the 
first word will contain the integer number of 
words actually transmitted when IRCVDC is 
complete . 

went is the maximum integer number of words to be 
received . 

crtn is the assembly language completion routine 
to be entered. This name must be specified 
in a FORTRAN EXTERNAL statement in the 
routine that issues the IRCVDC call. 



Errors; 



i = Normal return. 

=1 No foreground job exists in the system. 

IRCVDF 

The IRCVDF function receives data and enters a FORTRAN completion 
subroutine (see Section 0.2.1) when the message is received. The 
IRCVDF is queued and program execution continues with the issuing job. 
When the other job sends a message, the FORTRAN completion routine 
specified is entered. 

Form: i = IRCVDF (buf f, went, area, crtn) 

where: buff is the array to be used to buffer the data 

received. The array must be one word larger 
than the message to be received because the 
first word will contain the integer number of 
words actually transmitted when IRCVDF is 
complete . 
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went is the maximum integer number of words to be 
received . 

area is a 4-word area to be set aside for linkage 
information. This area must not be modified 
by the FORTRAN program and the USR must not 
swap over it. This area may be reclaimed by 
other FORTRAN completion routines when crtn 
has been entered. 

crtn is the FORTRAN completion routine to be 
entered. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine 
that issues the IRCVDF call. 



Errors: 



i = Normal return. 

=1 No foreground job exists in the system. 



Example ; 



INTEGER*2 MSG (41 ) ,AREA ( 4 ) 
EXTERNAL RMSGRT 



CALL IRCVDF (MSG, 40, AREA, RMSGRT) 

IRCVDW 

The IRCVDW function is used to receive data and wait. This function 
queues a message request and suspends the job issuing the request 
until the other job sends a message. When execution of the issuing 
job resumes, the message has been received, and the first word of the 
buffer indicates the number of words which were transmitted. 

Form: i = IRCVDW (buff, went) 

where: buff is- the array to be used to buffer the data 

received. The array must be one word larger 
than the message to be received because the 
first word will contain the integer number of 
words actually transmitted when IRCVDW is 
complete . 

went is the maximum integer number of words to be 
received . 



Errors : 



i = Normal return. 

=1 No foreground job exists in the system. 



Example : 



INTEGER*2 MSG (41) 

IF(IRCVDW(MSG,40) .NE.O) STOP 'UNEXPECTED ERROR 1 



0-57 



System Subroutine Library 



IREAD/IREADC/IREADF/IREADW 



0.3.36 IREAD/IREADC/IREADF/IREADW 

SYSLIB provides four modes of I/O: IREAD/IWRITE, IREADC/IWRITC, 
IREADF/IWRITF, and IREADW/IWRITW. Section 0.3.52 explains the output 
operations. These functions require a queue element; this should be 
considered when the IQSET function (Section 0.3.33) is executed. 

IREAD 

The IREAD function transfers a specified number of words from the file 
associated with the indicated channel into memory. Control returns to 
the user program immediately after the IREAD function is initiated. 
No special action is taken when the transfer is completed. 

Form: i = IREAD (went , buff ,blk ,chan) 

where: went is the integer number of words to be 

transferred . 

buff is the array to be used as the buffer. This 
array must contain at least went words. 

blk is the integer block number of the file to be 
read. The user program normally updates blk 
before it is used again. 

chan is the integer specification for the RT-11 
channel to be used. 

NOTE 

The "blk" argument must be updated, 
if necessary, by the user program. 
For example, if reading two blocks at 
a time, update blk by 2. 



When the user program needs to access the data read on the specified 
channel, an IWAIT function should be issued. This ensures that the 
IREAD operation has been completed. If an error occurred during the 
transfer, the IWAIT function indicates the error. 
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Errors: 



i = n Normal return; n equals the number of words read 

(0 for nonfile-structured read, multiple of 256 
for file-structured read) . For example: 

If went is a multiple of 256 and less than 
that number of words remain in the file, n is 
shortened to the number of words that remain 
in the file; e.g., if went is 512 and only 
256 words remain, i = 256. 

If went is not a multiple of 256 and more 
than went words remain in the file, n is 
rounded up to the next block; e.g., if went 
is 312 and more than 312 words remain, i = 
512, but only 312 are read. 

If went is not a multiple of 256 and less 
than went words remain in the file, n equals 
a multiple of 256 that is the actual number 
of words being read. 

= -1 Attempt to read past end-of-file; no words remain 

in the file. 
= -2 Hardware error occurred on channel. 
= -3 Specified channel is not open. 

Example : 

INTEGER*2 BUFFER (256 ) ,RCODE ,BLK 



RCODE = IREAD (256, BUFFER, BLK,ICHAN) 

IF(RC0DE+1) 1010,1000,10 
C IF NO ERROR, START HERE 
10 



IF(IWAIT(ICHAN) .NE.O) GOTO 1010 



1000 CONTINUE 

C END OF FILE PROCESSING 



CALL EXIT "NORMAL END OF PROGRAM 

1010 STOP 'FATAL READ' 
END 
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IREADC 

The IREADC function transfers a specified number of words from the 
indicated channel into memory. Control returns to the user program 
immediately after the IREADC function is initiated. When the 
operation is complete, the specified assembly language routine (crtn) 
is entered as an asynchronous completion routine. 

Form: i = IREADC (went, buf f,blk,chan , crtn) 

where: went is the integer number of words to be 

transferred . 

buff is the array to be used as the buffer. This 
array must contain at least went words. 

blk is the integer block number of the file to be 
read. The user program normally updates blk 
before it is used again. 

chan is the integer specification for the RT-11 
channel to be used. 

crtn is the assembly language routine to be 
activated when the transfer is complete. 
This name must be specified in an EXTERNAL 
statement in the FORTRAN routine that issues 
the IREADC call. 

Errors: 

See Errors under IREAD. 

Example : 

INTEGER*2 IBUF (256) ,RCODE , IBLK 
EXTERNAL RDCMP 



RCODE=IREADC (256, IBUF, IBLK, ICHAN,RDCMP) 

IREADF 

The IREADF function transfers a specified number of words from the 
indicated channel into memory. Control returns to the user program 
immediately after the IREADF function is initiated. When the 
operation is complete, the specified FORTRAN subprogram (crtn) is 
entered as an asynchronous completion routine (see Section 0.2.1). 

Form: i = IREADF (went , buf f, blk, chan , area, crtn) 

where: went is the integer number of words to be 

transferred . 

buff is the array to be used as the buffer. This 
array must contain at least went words. 



O-60 



System Subroutine Library 



bik is the integer block number of the file to be 
used. The user program normally updates bik 
before it is used again. 

chan is the integer specification for the RT-11 
channel to be used. 



area 



is a 4-word area to be set aside for linkage 
information; this area must not be modified 
by the FORTRAN program or swapped over by the 
USR. This area may be reclaimed by other 
FORTRAN completion functions when crtn has 
been activated. 

crtn is the FORTRAN routine to be activated on 
completion of the transfer. This name must 
be specified in an EXTERNAL statement in the 
routine that issues the IREADF call. The 
subroutine has two arguments: 

SUBROUTINE crtn ( iargl , iarg2) 

iargl is the channel status word (see 
Section 9.4.34) for the operation 
just completed. If bit is set, a 
hardware error occurred during the 
transfer . 

iarg2 is the octal channel number used 
for the operation just completed. 



Errors: 

See Errors under IREAD. 

Example : 



INTEGER*2 DBLK(4) ,BUFFER(256) ,BLKNO 

DATA DBLK/3RDX0,3RINP,3RUT , 3RDAT/ ,BLKNO/0/ 

EXTERNAL RCMPLT 



ICHAN=IGETC() 

IF(ICHAN.LT.O) STOP 'NO CHANNEL AVAILABLE" 

IF(IFETCH(DBLK) .NE.O) STOP 'BAD FETCH' 

IF (LOOKUP (ICHAN,DBLK) .LT.O) STOP 'BAD LOOKUP 1 



20 IF (IREADF (256, BUFFER, BLKNO , ICHAN ,DBLK, RCMPLT) .LT.O) GOTO 100 
C PERFORM OVERLAP PROCESSING 



SYNCHRONIZER 

CALL IWAIT (ICHAN) 1WAIT FOR COMPLETION ROUTINE TO RUN 

BLKNO=BLKNO+l "UPDATE BLOCK NUMBER 

GOTO 20 
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C END OF FILE PROCESSING 
100 CALL CLOSEC(ICHAN) 
CALL IFREEC(ICHAN) 



CALL EXIT 
END 

SUBROUTINE RCMPLT(I,J) 
C THIS IS THE COMPLETION ROUTINE 



RETURN 
END 

I READ W 

The IREADW function transfers a specified number of words from the 
indicated channel into memory. Control returns to the user program 
when the transfer is complete or when an error is detected. 

Form: i = IREADW (went , buff ,blk,chan) 

where: went is the integer number of words to be 

transferred. 

buff is the array to be used as the buffer. This 
array must contain at least went words. 

blk is the integer block number of the file to be 
read. The user program normally updates blk 
before it is used again. 

chan is the integer specification for the RT-11 
channel to be used. 

Errors: 

See Errors under IREAD. 

Example : 

INTEGER*2 IBUF(1024) 



ICODE=IREADW(1024,IBUF,IBLK,ICHAN) 

IF(ICODE.EQ.-l) GOTO 100 "END OF FILE PROCESSING AT 100 

IF(ICODE.LT.-l) GOTO 200 ! ERROR PROCESSING AT 200 

C MODIFY BLOCKS 
C 



C 

C WRITE THEM OUT 



C 



ICODE=IWRITW(1024,IBUF,IBLK,ICHAN) 
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IRENAM 



0.3.37 IRENAM 

The IRENAM function causes an immediate change of the name of a 
specified file. An error occurs if the channel specified is already 
open. 



Form: i = IRENAM (chan,dblk) 



where : 



chan 



dblk 



is the integer specification for the 
channel to be used for the operation. 



RT-11 



is the 8-word area specifying the name of the 
existing file and the new name to be 
assigned. If considered as an 8-element 
INTEGER*2 array, dblk has the form: 



dblk(l)-dblk(4) 
dblk(5)-dblk(8) 



specify the Radix-50 file 
descriptor for the old 
file name. 

specify the Radix-50 file 
descriptor for the new 
file name. 



NOTE 

The arguments of IRENAM must be 
positioned so that the USR does not 
swap over them. 



If a file with the same name as the new file name specified already 
exists on the indicated device, it is deleted. The specified channel 
is left closed when the IRENAM is complete. IRENAM requires that the 
handler to be used be resident at the time the IRENAM is issued. If 
it is not, a monitor error occurs. The device names specified in the 
file descriptors must be the same. 



For more information on renaming 
.RENAME request, Section 9.4.32. 

Errors : 



files, see the assembly language 



i = Normal return. 

= 1 Specified channel is already open, 
= 2 Specified file was not found. 
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Example : 



REAL*8 NAME (2) 

DATA NAME/12RDK0FTN2 DAT , 12RDK0FTN2 OLD/ 



ICHAN=IGETC() 

IF(ICHAN.LT.O) STOP 'NO CHANNEL 1 

CALL IRENAM(ICHAN,NAME) ! PRESERVE OLD DATA FILE 

CALL IFREEC(ICHAN) 



IREOPN 



0.3.38 IREOPN 

The IREOPN function reassociates a specified channel with a file on 
which an ISAVES was performed (see Section 0.3.39). The ISAVES/IREOPN 
combination is useful when a large number of files must be operated on 
at one time. As many files as are needed can be opened with LOOKUP 
and their status preserved with ISAVES. When data is required from a 
file, an IREOPN enables the program to read from the file. The IREOPN 
need not be done on the same channel as the original LOOKUP and 
ISAVES. 



Form: i = IREOPN (chan,cblk) 
where: chan 



cblk 



is the integer specification for the RT-11 
channel to be associated with the reopened 
file. This channel must be initially in an 
inactive state. 

is the 5-word block where the channel status 
information was stored by a previous ISAVES. 
This block, considered as a 5-element 
INTEGER*2 array, has the following format: 



cblk(l) 
cblk (2) 

cblk (3) 

cbl k ( 4 ) 
cblk (5) 



Channel status word 
Section 9.4.33) . 
Starting block number of 
file; zero for non 
structured devices. 
Length of file (in 256 
blocks) . 

(Reserved for future use.) 
Two information bytes, 
byte: I/O count of the n 
of requests made on 
channel. Odd byte: 
number of the device assoc 
with the channel. 



(see 

the 
file- 

-word 



Even 

umber 

this 

unit 

iated 
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Errors : 



i = Normal return. 

= 1 Specified channel is already in use, 



Example ; 



INTEGER*2 SAVES (5,10) 
DATA ISVPTR/1/ 



CALL ISAVES (ICHAN, SAVES (1,ISVPTR) ) 



CALL IREOPN (ICHAN, SAVES (1 , ISVPTR) ) 




0.3.39 ISAVES 

The ISAVES function stores five words of channel status information 
into a user-specified array. These words contain all the information 
that RT-11 requires to completely define a file. When an ISAVES is 
finished, the data words are placed in memory and the specified 
channel is closed and is again available for use. When the saved 
channel data is required, the IREOPN function (Section 0.3.38) is 
used . 

ISAVES can be used only if a file was opened with a LOOKUP call (see 
Section 0.3.66). If IENTER was used, ISAVES is illegal and returns an 
error. Note that ISAVES is not legal on magtape or cassette files. 

Form: i = ISAVES (chan,cblk) 

where: chan is the integer specification for the RT-11 

channel whose status is to be saved. 

cblk is a 5-word block into which the channel 
status information describing the open file 
is stored. See Section 0.3.38 for the format 
of this block. 

The ISAVES/IREOPN combination is very useful, but care must be 
observed when using it. In particular, the following cases should be 
avoided . 

1. If an ISAVES is performed on a file and the same file is then 
deleted before it is reopened, the space occupied by the file 
becomes available as an empty space which could then be used 
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by the IENTER function. If this sequence occurs, the 
contents of the file whose status was supposedly saved will 
change . 

2. Although the handler for the required peripheral need not be 
in memory for execution of an IREOPN, a fatal error is 
generated if the handler is not in memory when an IREAD or 
IWRITE is executed. 

Errors: 

i = Normal return. 

= l The specified channel is not currently associated 

with any file. 
= 2 The file was opened with an IENTER call; an 

ISAVES is illegal. 

Example : 

INTEGER*2 BLK(5) 



IF (ISAVES (ICHAN,BLK) .NE.O) STOP 'ISAVES ERROR' 



ISCHED 



0.3. 40 ISCHED (F/B Only) 

The ISCHED function schedules a specified FORTRAN subroutine to be run 
as an asynchronous completion routine at a specified time-of-day. 

Form: i = ISCHED (hrs ,min, sec , tick, area , id ,crtn) 

where: hrs is the integer number of hours. 

min is the integer number of minutes. 

sec is the integer number of seconds. 

tick is the integer number of ticks (1/60 of a 
second on 60-cycle clocks; 1/50 of a second 
on 50-cycle clocks) . 

area is a 4-word-area which must be provided for 
linkage information; this area must never be 
modified by the FORTRAN program, and the USR 
must not swap over it. This area may be 
reclaimed by other FORTRAN completion 
functions when crtn has been activated. 
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id is the identification integer to be passed to 
the routine being scheduled. 

crtn is the name of the FORTRAN subroutine to be 
entered at the time-of-day specified. This 
name must be specified in an EXTERNAL 
statement in the FORTRAN routine that issues 
the ISCHED call. The subroutine has one 
argument, e.g., 

SUBROUTINE crtn (id) 
INTEGER id 

When the routine is entered, the value of the 
integer argument will be the value specified 
for id in the appropriate ISCHED call. 



Notes ! 



1. The scheduling request made by this function may be cancelled 
at a later time by an ICMKT function call. 

2. If the system is busy, the actual time-of-day that the 
completion routine is run may be greater than the requested 
time-of-day. 

3. A FORTRAN subroutine may periodically reschedule itself by 
issuing its own ISCHED or ITIMER calls from within the 
routine . 

4. ISCHED requires a queue element; this should be considered 
when the IQSET function (Section 0.3.33) is executed. 



Errors : 



i = Normal return. 

=1 No queue elements available; unable to schedule 
request. 



Example: 



INTEGER*2 LINK (4) 1LINKAGE AREA 

EXTERNAL NOON ! NAME OF ROUTINE TO RUN 



I=ISCHED (12, 0,0,0, LINK, 0, NOON) ! RUN SUBR NOON AT 12 PM 
(rest of main program) 

END 

SUBROUTINE NOON (ID) 
C 

C THIS ROUTINE WILL TERMINATE EXECUTION AT LUNCHTIME , 
C IF THE JOB HAS NOT COMPLETED BY THAT TIME. 
C 

STOP 'ABORT JOB — LUNCHTIME' 

END 
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ISDAT/lSDATC/ISDATF/iSDATW 



0.3.41 ISDAT/ISDATC/ISDATF/ISDATW (F/B only) 

These functions are used with the IRCVD/IRCVDC/IRCVDF, and IRCVDW 
calls to allow message transfers under the F/B Monitor. Note that the 
buffer containing the message should not be modified or reused until 
the message has been received by the other job. These functions 
require a queue element; this should be considered when the IQSET 
function (Section 0.3.33) is executed. 

ISDAT 

The ISDAT function transfers a specified number of words from one job 
to the other. Control returns to the user program immediately after 
the transfer is queued. This call is used with the MWAIT routine (see 
Section 0.3.68) . 

Form: i = ISDAT (buff, went) 

where: buff is the array containing the data to be 

transferred . 

went is the integer number of data words to be 
transferred . 



Errors: 



i = Normal return. 

=1 No foreground job currently exists in the system, 



Example : 



INTEGER*2 MSG(40) 



CALL ISDAT(MSG,40) 



CALL MWAIT 

PUT NEW MESSAGE IN BUFFER 
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ISDATC 



The ISDATC function transfers a specified number of words from one job 
to another. Control returns to the user program immediately after the 
transfer is queued. When the other job accepts the message through a 
receive data request, the specified assembly language routine (crtn) 
is activated as an asynchronous completion routine. 

Form: i = ISDATC (buf f, went , crtn) 

where: buff is the array containing the data to be 

transferred . 

went is the integer number of data words to be 
transferred. 

crtn is the name of an assembly language routine 
to be activated on completion of the 
transfer. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine 
that issues the ISDATC call. 



Errors : 



= Normal return. 

= 1 No foreground job currently exists in the system. 



Example : 



INTEGER*2 MSG(40) 
EXTERNAL RTN 



CALL ISDATC (MSG, 40, RTN) 

ISDATF 

The ISDATF function transfers a specified number of words from one job 
to the other. Control .returns to the user program immediately after 
the transfer is queued and execution continues. When the other job 
accepts the message through a receive data request, the specified 
FORTRAN subprogram (crtn) is activated as an asynchronous completion 
routine (see Section 0.2.1). 

Form: i = ISDATF (buf f , went , area , crtn) 

where: buff is the array containing the data to be 

transferred . 

went is the integer number of data words to be 
transferred . 

area is a 4-word area to be set aside for linkage 
information; this area must not be modified 
by the FORTRAN program and the USR must not 
swap over it. This area may be reclaimed by 
other FORTRAN completion functions when crtn 
has-been activated. 
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crtn is the name of a FORTRAN routine to be 
activated on completion of the transfer. 
This name must be specified in an EXTERNAL 
statement in the FORTRAN routine that issues 
the ISDATF call. 



Errors : 



i = Normal return. 

=1 No foreground job currently exists in the system- 



Example! 



INTEGER*2 MSG (40) ,SPOT (4) 
EXTERNAL RTN 



CALL ISDATF (MSG, 40, SPOT, RTN) 

ISDATW 

The ISDATW function transfers a specified number of words from one job 
to the other. Control returns to the user program when the other job 
has accepted the data through a receive data request. 

Form: i = ISDATW (buff, went) 

where: buff is the array containing the data to be 

transferred. 

went is the integer number of data words to be 
transferred . 



Errors ; 



i = Normal return. 

=1 No foreground job currently exists in the system. 



Example: 



INTEGER*2 MSG (40) 



IF (ISDATW(MSG,40) .NE.O) STOP 'FOREGROUND JOB NOT RUNNING' 
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ISLEEP 



0.3.42 ISLEEP (F/B Only) 

The ISLEEP function suspends the main program execution of a job for a 
specified amount of time. The specified time is the sum of hours, 
minutes, seconds, and ticks specified in the ISLEEP call. All 
completion routines continue to execute. 

Form: i = ISLEEP (hrs, min, sec , tick) 

where: hrs is the integer number of hours. 

min is the integer number of minutes. 

is the integer number of seconds. 



sec 
tick 



is the integer number of ticks (1/60 of a 
second on 60-cycle clocks; 1/50 of a second 
on 50-cycle clocks) . 



Notes: 



1. ISLEEP requires a queue element; this should be considered 
when the IQSET function (Section 0.3.33) is executed. 

2. If the system is busy, the time that execution is suspended 
may be greater than that specified. 



Errors : 



i = 
= 1 



Normal return. 

No queue element available. 



Example : 



CALL IQSET (2) 



CALL ISLEEP(0,0,0,4) 



IGIVE BACKGROUND JOB SOME TIME 
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ISPFN/ISPFNC/ISPFNF/ISPFNW 



0.3.43 ISPFN/ISPFNC/ISPFNF/ISPFNW 

These functions are used in conjunction with special functions to 
various handlers (cassette, diskette, and magtape). They provide a 
means of doing device-dependent functions, such as rewind and 
backspace, to those devices. If ISPFN function calls are made to any 
other devices, the function call is ignored. 

To use these functions, the handler must be in memory and a channel 
associated with a file via a non-file structured LOOKUP call. These 
functions require a queue element; this should be considered when the 
IQSET function (Section 0.3.33) is executed. Refer to Appendix H for 
details of CT, DX, and MT handlers. 

ISPFN 

The ISPFN function queues the specified operation and immediately 
returns control to the user program. The IWAIT function may be used 
to ensure completion of the operation. 

Form: i = ISPFN (code ,chan{ „wcnt, buff ,blk }) 

where: code is the integer numeric code of the function 

to be performed (see Table 0-2). 

chan is the integer specification for the RT-11 
channel to be used for the operation. 

went is the inteqer number of data words in the 
operation. * 

buff is the array to be used as the data 
buffer. 1 

blk is the integer block number of the file to be 
operated upon . 1 



'These optional parameters are required only when doing a write 
with extended record gap to MT or a read or write to DX. If specified 
and not required, these arguments must be 0. 
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Table 0-2 
Special Function Codes (Octal) 



Function 


MT 


CT 


DX 


Read absolute 






377 


Write absolute 






376 


Write absolute with 








deleted data 






375 


Backspace to last file 




377 




Backspace to last block 




376 




Forward to next file 




375 




Forward to next block 




374 




Rewind to load point 


373 


373 




Write file gap 




372 




Write EOF 


377 






Forward 1 record 


376 






Backspace 1 record 


375 






Write with extended 








record gap 


374 






Offline 


372 







Errors : 



i = Normal return. 

= 1 Attempt to read or write past end-^f-file. 

= 2 Hardware error occurred on channel. 

= 3 Channel specified is not open. 



Example : 



CALL ISPFN("373,ICHAN) 



! REWIND 



ISPFNC 

The ISPFNC function queues the specified operation and immediately 
returns control to the user program. When the operation is complete, 
the specified assembly language routine (crtn) is entered as an 
asynchronous completion routine. 

Form: i = ISPFNC (code ,chan , went , buff ,blk , crtn) 

where: code is the integer numeric code of the function 

to be performed (see Table 0-2) . 

chan is the integer specification for the RT-11 
channel to be used for the operation. 

went is the integer number of data words in the 
operation. This argument must be if not 
required . 

buff is the array to be used as the data buffer. 
This argument must be if not required. 

blk is the integer block number of the file to be 
operated upon. This argument must be if 
not required. 
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crtn is the name of an assembly language routine 
to be activated on completion of the 
operation. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine 
that issues the ISPFNC call. 



Errors : 



i = Normal return. 

= 1 Attempt to read or write past end-of-file. 

= 2 Hardware error occurred on channel. 

= 3 Channel specified is not open. 

ISPFNF 

The ISPFNF function queues the specified operation and immediately 
returns control to the user program. When the operation is complete, 
the specified FORTRAN subprogram (crtn) is entered as an asynchronous 
completion routine. 

Form: i = ISPFNF (code, chan f wcnt , buff ,blk, area , crtn) 

where: code is the integer numeric code of the function 

to be performed (see Table 0-2) . 

chan is the integer specification for the RT-11 
channel to be used for the operation. 

went is the integer number of data words in the 
operation. This argument must be if not 
required . 

buff is the array to be used as the data buffer. 
This argument must be if not required. 

blk is the integer block number of the file to be 
operated upon. This argument must be if 
not required. 

area is a 4-word area to be set aside for linkage 
information; this area must not be modified 
by the FORTRAN program and the USR must not 
swap over it. This area may be reclaimed by 
other FORTRAN completion functions when crtn 
has been activated. 

crtn is the name of a FORTRAN routine to be 
activated on completion of the operation. 
This name must be specified in an EXTERNAL 
statement in the FORTRAN routine that issues 
the ISPFNF call. The subroutine has two 
arguments : 

SUBROUTINE crtn (iargl , iarg2) 

iargl is the channel status word (see 
Section 9.4.34) for the operation 
just completed. If bit is set, a 
hardware error occurred during the 
transfer . 

iarg2 is the channel number used for the 
operation just completed. 
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Errors : 



i = Normal return. 

= 1 Attempt to read or write past end-of-file, 

= 2 Hardware error occurred on channel. 

= 3 Channel specified is not open. 



Example : 



REAL*4 MTNAME(2) ,AREA(2) 
DATA MTNAME/3RMT0,0./ 
EXTERNAL DONSUB 



I=IGETC() 'ALLOCATE CHANNEL 

CALL IFETCH(MTNAME) ! FETCH MT HANDLER 

CALL LOOKUP ( I, MTNAME) J NON-FILE STRUCTURED LOOKUP ON MTO 

IERR=ISPFNF("373, I, 0,0,0, AREA, DONSUB) "REWIND MAGTAPE 



END 

SUBROUTINE DONSUB 
C 

C RUNS WHEN MTO HAS BEEN REWOUND 
C 



END 

ISPFNW 

The ISPFNW function queues the specified operation and returns control 
to the user program when the operation is complete. 

Form: i = ISPFNW (code ,chan{ , went , buff ,blk}) 

where: code is the integer numeric code of the function 

to be performed (see Table 0-2) . 

chan is the integer specification for the RT-11 
channel to be used for the operation. 

went is the integer number of data words in the 
operation. l 

buff is the array to be used as the data 
buffer. l 

blk is the integer block number of tne file to be 
operated upon. 1 



These optional parameters are required only when doing a write 
with extended record gap to MT or a read or write to DX. If specified 
and not required, these arguments must be 0. 
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Errors : 



i = Normal return. 

= 1 Attempt to read or write past end-of-f ile , 

= 2 Hardware error occurred on channel. 

= 3 Channel specified is not open. 



Example : 



INTEGER*2 BUF(65) , TRACK , SECTOR, DBLK (4) 
DATA DBLK/3RDX0, 0,0,0/ 



ICHAN=IGETC() 

IF(ICHAN.LT.O) STOP 'NO CHANNEL AVAILABLE' 

IF (LOOKUP (ICHAN, DBLK) .LT.O) STOP 'BAD LOOKUP' 



C 
C 

c 
c 
c 



READ AN ABSOLUTE TRACK AND SECTOR FROM THE FLOPPY 

ICODE=ISPFNW ( " 377 , ICHAN , TRACK ,BUF , SECTOR) 

BUF(l) IS THE DELETED DATA FLAG 
BUF(2-65) IS THE DATA 




0.3.44 ISPY 

The ISPY function returns the integer value of the word at a specified 
offset from the RT-11 resident monitor. (See Section 9.2.6 for 
information on fixed offset references.) 

Form: i = ISPY (ioff) 

where: ioff is the offset (from the base of RMON) to be 

examined . 

Function Result: 

The function result (i) is set to the value of the word examined. 

Example: 



C 
C 

C 

C 

c 
c 



BRANCH TO 200 IF RUNNING UNDER F/B MONITOR 

IF(ISPY("300) .AND.l) GOTO 200 

WORD AT OCTAL 300 FROM RMON IS 
THE CONFIGURATION WORD. 
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0.3.45 ITIMER (F/B Only) 

The ITIMER function schedules a specified FORTRAN subroutine to be run 
as an asynchronous completion routine after a specified time interval 
has elapsed. 

Form: i = ITIMER (hrs ,min , sec , tick, area , id ,crtn) 

where: hrs is the integer number of hours. 

min is the integer number of minutes 

sec is the integer number of seconds. 

tick is the integer number of ticks (1/60 of a 
second on 60-cycle clocks; 1/50 of a second 
on 50-cycle clocks) . 

area is a 4-word area which must be provided for 
linkage information; this area must never be 
modified by the FORTRAN program, and the USR 
must never swap over it. This area may be 
reclaimed by other FORTRAN completion 
functions when crtn has been activated. 

id is the identification integer to be passed to 
the routine being scheduled. 

crtn is the name of the FORTRAN subroutine to be 
entered when the specified time interval 
elapses. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine 
that references ITIMER. The subroutine has 
one argument, e.g., 

SUBROUTINE crtn (id) 
INTEGER id 

When the routine is entered, the value of the 
integer argument will be the value specified 
for id in the appropriate ITIMER call. 



Notes : 



1. This function may be cancelled at a later time by an ICMKT 
function call. 
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2. If the system is busy, the actual time interval at which the 
completion routine is run may be greater than the time 
interval requested. 

3. FORTRAN subroutines can periodically re-schedule themselves 
by issuing ISCHED or ITIMER calls. 

4. ITIMER requires a queue element; this should be considered 
when the IQSET function (Section 0.3.33) is executed. 

For more information on scheduling completion routines, see Section 
0.2.1 and the assembly language .MRKT request, Section 9.4.22. 



Errors: 



i = Normal return 

=1 No queue elements available; unable to schedule 

request . 



Example: 



C 



INTEGER*2 AREA (4) 
EXTERNAL WATCHD 



C IF THE CODE FOLLOWING ITIMER DOES NOT REACH THE ICMKT CALL 
C IN 12 MINUTES, WATCH DOG COMPLETION ROUTINE WILL BE 
C ENTERED WITH ID OF 3 



CALL ITIMER (0 , 12 ,0,0 , AREA, 3 , WATCHD) 



CALL ICMKT (3, AREA) 



END 

SUBROUTINE WATCHD (ID) 
C 
C THIS IS CALLED AFTER 12 MINUTES 



RETURN 
END 
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0.3.46 ITLOCK (F/B Only) 

The ITLOCK function is used in an F/B system to attempt to gain 
ownership of the USR. It is similiar to LOCK (Section 0.3.65) in that 
if successful, the user job returns with the USR in memory. However, 
if a job attempts to LOCK the USR while the other job is using it, the 
requesting job is suspended until the USR is free. With ITLOCK, if 
the USR is not available, control returns immediately and the lock 
failure is indicated. ITLOCK cannot be called from a completion or 
interrupt routine. 



Form: 



ITLOCK () 



For further information on gaining ownership of 
assembly language .TLOCK request, Section 9.4.41. 



the USR, see the 



Errors : 



i = Normal return. 

= 1 USR is already in use by another job. 



Example: 



IF(ITLOCK() .NE.O) GOTO 100 



1GOTO 100 IF USR BUSY 



ITTINR 



0.3.47 ITTINR 

The ITTINR function transfers a character from the console terminal to 
the user program. If no characters are available, return is made with 
an error flag set. 



Form: 



ITTINR () 
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If the function result (i) is less than zero when execution of the 
ITTINR function is complete, it indicates that no character was 
available; the user has not yet typed a valid line. Under the F/B 
Monitor, ITTINR does not return a result of less than zero unless bit 
6 of the Job Status Word was on when the request was issued (see 
below) . 

There are two modes of doing console terminal input. The mode is 
governed by bit 12 of the Job Status Word (JSW) . The JSW is at octal 
location 44. If bit 12 equals 0, normal I/O is performed. In this 
mode, the following conditions apply: 

1. The monitor echoes all characters typed; lower case 
characters are converted to upper case unless JSW bit 14 is 
set, in which case lower case characters are not translated. 

2. CTRL U (~U) AND RUBOUT perform line deletion and character 
deletion, respectively. 

3. A carriage return, line feed, CTRL Z, or CTRL C must be 
struck before characters on the current line are available to 
the program. When one of these is typed, characters on the 
line typed are passed one-by-one to the user program. Both 
carriage return and line feed are passed to the program. 

4. ALTMODEs (octal codes 175 and 176) are converted to ESCAPES 
(octal 33) . 

If bit 12 equals 1, the console is in special mode. The effects are: 

1. The monitor does not echo characters typed except for CTRL C 
and CTRL 0. 

2. CTRL U and RUBOUT do not perform special functions. 

3. Characters are immediately available to the program. 

4. No ALTMODE conversion is done. 

In special mode, the user program must echo the characters desired. 
However, CTRL C and CTRL are acted on by the monitor in the usual 
way. Bits 12 and 14 in the JSW must be set by the user program if 
special console mode or lower case characters are desired (see the 
example under Section 0.3.32). These bits are cleared when control 
returns to RT-11. 

NOTE 

To set and/or clear bits in the JSW, do 
an IPEEK and then an IPOKE. In special 
terminal mode (JSW bit 12 set) , normal 
FORTRAN formatted I/O from the console 
is undefined. 



In the F/B Monitor, CTRL F and CTRL B are not affected by the setting 
of bit 12. The monitor always acts on these characters if the SET TT¥ 
FB command was issued. 
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Under the F/B Monitor, if a terminal input request is made and no 
character is available, job execution is suspended until a character 
is ready. If a program really requires execution to continue and 
ITTINR to return a result of less than zero, it must turn on bit 6 of 
the JSW before the ITTINR. Bit 6 is cleared when a program 
terminates. 

Function Results: 

i >0 Normal return; character read. 

<0 Error return; no character available. 



Example ; 



ICHAR=ITTINR() ! READ A CHARACTER FROM THE CONSOLE 

IF(ICHAR.LT.O) GOTO 100 ! CHARACTER NOT AVAILABLE 



ITTOUR 



0.3.48 ITTOUR 

The ITTOUR function transfers a character from the user program to the 
console terminal if there is room for the character in the monitor 
buffer. If it is not currently possible to output a character, an 
error flag is returned. 

Form: i = ITTOUR (char) 

where: char is the character to be output, 

right-justified in the integer (may be 
LOGICAL*l entity if desired) . 

If the function result (i) is 1 when execution of the ITTOUR function 
is complete, it indicates that there is no room in the buffer and that 
no character was output. Under the F/B Monitor, ITTOUR normally does 
not return a result of 1. Instead, the job is blocked until room is 
available in the output buffer. If a job really requires execution to 
continue and a result of 1 to be returned, it must turn on bit 6 of 
the JSW (location 44) before issuing the request. 

The ITTINR and ITTOUR have been supplied as a help to those users who 
do not wish to suspend program execution until a console operation is 
complete. With these modes of I/O, if a no-character or no-room 
condition occurs, the user program can continue processing and try the 
operation again at a later time. 



Errors : 



Normal return; character was output. 

1 Error return; ring buffer is full. 
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Example ; 



10 
20 



DO 20 1=1,5 

IF(ITTOUR("007) .NE.O) GOTO 10 

CONTINUE 



RING BELL 5 TIMES 



ITWAIT 



0.3.49 ITWAIT (F/B Only) 

The ITWAIT function suspends the main program execution of the current 
job for a specified time interval. All completion routines continue 
to execute. 

Form: i = ITWAIT (itime) 

where: itime is the 2-word internal format time interval. 

itime (1) is the high-order time, 
itime (2) is the low-order time. 



Notes : 
1. 



ITWAIT requires a queue element; this should be considered 
when the IQSET function (Section 0.3.33) is executed. 

If the system is busy, the actual time interval that 
execution is suspended may be greater than the time interval 
specified . 



Errors : 
i 

Example: 



= 
= 1 



Normal return. 

No queue element available. 



INTEGER*2 TIME (2) 



CALL ITWAIT (TIME) 



IWAIT FOR TIME TIME 
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0.3. 50 IUNTIL (F/B Only) 

The IUNTIL function suspends main program execution of the job until 
the time-of-day specified. All completion routines continue to run. 

Form: i = IUNTIL (hrs ,min , sec , tick) 

where: hrs is the integer number of hours. 

min is the integer number of minutes. 

sec is the integer number of seconds. 

tick is the integer number of ticks (1/60 of a 
second on 60-cycle clocks; 1/50 of a second 
on 50-cycle clocks) . 



Notes: 



1. IUNTIL requires a queue element; this should be considered 
when the IQSET function (Section 0.3.33) is executed. 

2. If the system is busy, the actual time-of-day that the 
program resumes execution may be later than that requested. 



Errorsi 



i = Normal return. 

=1 No queue element available, 



Example ; 



TAKE A LUNCH BREAK 

CALL IUNTIL(13, 0,0,0) ! START UP AGAIN AT 1 P.M. 
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0.3.51 IWAIT 

The IWAIT function suspends execution of the main program until all 
input/output operations on the specified channel are complete. This 
function is used with IREAD, IWRITE, and ISPFN calls. Completion 
routines continue to execute.. 



Form: i = IWAIT (chan) 
where: chan 



is the integer specification for the RT-11 
channel to be used. 



For further information on suspending execution of the main program, 
see the assembly language .WAIT request, Section 9.4.46. 



Errors: 



i = 
= 1 
= 2 



Normal return. 

Channel specified is not open. 

Hardware error occurred during the previous I/O 

operation on this channel . 



Example ; 



IF (IWAIT (ICHAN) .NE.O) CALL I0ERR(4) 



IWRITC/IWRITE/IWRITF/IWRITW 



0.3.52 IWRITC/IWRITE/IWRITF/IWRITW 

These functions transfer a specified number of words from memory to 
the specified channel. The IWRITE functions require queue elements; 
this should be considered when the IQSET function (Section 0.3.33) is 
executed . 
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IWRITC 

The IWRITC function transfers a specified number of words from memory 
to the specified channel. The request is queued and control returns 
to the user program. When the transfer is complete, the specified 
assembly language routine (crtn) is entered as an asynchronous 
completion routine. 

Form: i = IWRITC (went , buff ,blk,chan , crtn) 

where: went is the integer number of words to be 

transferred . 

buff is the array to be used as the output buffer. 

blk is the integer block number of the file to be 
written. The user program normally updates 
blk before it is used again. 

chan is the integer specification for the RT-11 
channel to be used . 

crtn is the name of the assembly language routine 
to be activated upon completion of the 
transfer. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine 
that issues the IWRITC call. 

NOTE 

The "blk" argument must be updated, 
if necessary, by the user program. 
For example, if writing two blocks at 
a time, update blk by 2. 



Errors: 



i = n Normal return; n equals the number of words 

written, rounded to a multiple of 256 (0 for 
nonfile-structured writes) . 



NOTE 



If the word count returned is less than 
that requested, an implied end-of-file has 
occurred although the normal return is 
indicated . 



= -1 Attempt to write past end-of-file; no more space 

is available in the file. 
= -2 Hardware error occurred. 
= -3 Channel specified is not open. 
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Example: 

INTEGER*2 IBUF(256) 
EXTERNAL CRTN 



ICODE*IWRITC (2 56 , IBUF , IBLK , ICHAN , CRTN J 



IWRITE 



The IWRITE function transfers a specified number of words from memory 
to the specified channel. Control returns to the user program 
immediately after the request is queued. No special action is taken 
upon completion of the operation. 

Forms i = IWRITE (wcnt,buf f ,blk ,chan) 

where: went is the integer number of words to be 

transferred. 

buff is the array to be used as the output buffer,, 

blk is the integer block number of the file to be 
written. The user program normally updates 
blk before it is used again. 

chan is the integer specification for the RT-11 
channel to be used. 

Errors: 

See Errors under IWRITC. 

Example: 

See the example under IREAD, Section 0.3.36. 

IWRITF 

The IWRITF function transfers a number of words from memory to the 
specified channel. The transfer request is queued and control returns 
to the user program. When the operation is complete, the specified 
FORTRAN subprogram (crtn) is entered as an asynchronous completion 
routine (see Section 0.2.1). 

Form: i = IWRITF (went, buff, blk, chan , area, crtn) 

where: went is the integer number of words to be 

transferred. 

buff is the array to be used as the output buffer. 

blk is the integer block number of the file to be 
written. The user program normally updates 
blk before it is used again. 

chan is the integer specification for the RT-11 
channel to be used. 
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area is a 4-word area to be set aside for linkage 
information; this area must not be modified 
by the FORTRAN program and the USR must not 
swap over it. This area may be reclaimed by 
other FORTRAN completion functions when crtn 
has been activated. 

crtn is the name of the FORTRAN routine to be 
activated upon completion of the transfer. 
This name must be specified in an EXTERNAL 
statement in the FORTRAN routine that issues 
the IWRITF call. The subroutine has two 
arguments : 

SUBROUTINE crtn (iargl, iarg2) 

iargl is the channel status word (see 
Section 9.4.34) for the operation 
just completed. If bit is set, a 
hardware error occurred during the 
transfer . 

iarg2 is the channel number used for the 
operation just completed. 

Errors: 

See Errors under IWRITC. 

Example : 

See the example under IREADF, Section 0.3.36. 

IWRITW 

The IWRITW function transfers a specified number of words from memory 
to the specified channel. Control returns to the user program when 
the transfer is complete. 

Form: i = IWRITW (went , buff ,blk,chan) 

where: went is the integer number of words to be 

transferred . 

buff is the array to be used as the output buffer. 

blk is the integer block number of the file to be 
written. The user program normally updates 
blk before it is used again. 

chan is the integer specification for the RT-11 
channel to be used. 

Errors: 

See Errors under IWRITC. 

Example: 

See the example under IREADW, Section 0.3.36. 
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0.3.53 JADD 

The JADD function computes the sum of two INTEGER*4 values, 

Form: i = JADD { jopr 1, jopr2, jres) 



where: joprl 

jopr2 

jres 

Function Results: 

i = -2 
= -1 
= 
= 1 



is an INTEGER*4 variable. 

is an INTEGER*4 variable. 

is an INTEGER*4 variable that receives the 
sum of joprl and jopr2. 



An overflow occurred while computing the result- 
Normal return; the result is negative. 
Normal return; the result is zero. 
Normal return; the result is positive. 



Example: 



INTEGER*4 J0P1 , J0P2 , JRES 



IF (JADD (J0P1,J0P2, JRES) .EQ.-2) GOTO 100 




0.3.54 JAFIX 

The JAFIX function converts a REAL*4 value to INTEGER*4, 

Form: i = JAFIX (asrc,jres) 
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where: asrc is a REAL*4 variable, constant, or expression 

to be converted to INTEGER*4. 

jres is an INTEGER*4 variable that is to contain 
the result of the conversion. 

Function Results: 

i = -2 An overflow occurred while computing the result. 

= -1 Normal return; the result is negative. 

= Normal return; the result is zero. 

= 1 Normal return; the result is positive. 

Example : 

INTEGER*4 JOPl 
C READ A LARGE INTEGER FROM THE TERMINAL 

ACCEPT 99, A 
99 FORMAT (F15.0) 

IF(JAFIX(A,JOPl) .EQ.-2) GOTO 100 




0.3.55 JCMP 

The JCMP function compares two INTEGER*4 values and returns an 
INTEGER*2 value that reflects the signed comparison result. 

Form: i = JCMP { jopr 1, jopr2) 

where: joprl is the INTEGER*4 variable or array element 

that is the first operand in the comparison. 

jopr2 is the INTEGER*4 variable or array element 
that is the second operand in the comparison. 

Function Result: 

i = -1 If joprl is less than jopr2 
=0 If joprl is equal to jopr2 
=1 If joprl is greater than jopr2 

Example : 

INTEGER*4 J0PX,J0PY 



IF(JCMP(JOPX,JOPY) ) 10,20,30 
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0.3.56 JDFIX 

The JDFIX function converts a REAL*8 (DOUBLE PRECISION) value to 
INTEGER*4. 

Form: i = JDFIX (dsrc,jres) 

where: dsrc is a REAL*8 variable, constant, or expression 

to be converted to INTEGER*4. 

jres is an INTEGERM variable to contain the 
conversion result. 

Function Results: 

i = -2 An overflow occurred while computing the result. 

= -1 Normal return; the result is negative. 

= Normal return; the result is zero. 

= 1 Normal return; the result is positive. 



Example : 



INTEGERM JNUM 
REAL*8 DPNUM 



20 TYPE 98 

98 FORMAT (' ENTER POSITIVE INTEGER') 
ACCEPT 99, DPNUM 

99 FORMAT (F20.0) 

IF (JDFIX (DPNUM, JNUM) .LT.O) GOTO 20 
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0.3.57 JDIV 

The JDIV function computes the quotient of two INTEGER*4 values. 

Form: i = JDIV ( joprl, jopr2 , jres{ , jrem}) 

where: joprl is an INTEGERM variable that is the dividend 

of the operation. 

jopr2 is an INTEGER*4 variable that is divisor of 
joprl. 

jres is an INTEGER*4 variable that receives the 
quotient of the operation (i.e., 
jres=joprl/jopr2) . 

jrem is an INTEGER*4 variable that receives the 
remainder of the operation. The sign is the 
same as that for joprl. 



Function Results; 



1 = 


-3 


= 


-2 


== 


-1 


= 





== 


1 


le: 





An attempt was made to divide by zero, 
(not used) 

Normal return; the quotient is negative. 
Normal return; the quotient is zero. 
Normal return; the quotient is positive. 



INTEGER*4 JN1 , JN2 , JQUO 



CALL JDIV (JN1,JN2, JQUO) 
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0.3.58 JICVT 

The JICVT function converts a specified INTEGER*2 value to INTEGER*4. 

Form: i = JICVT (isrc,jres) 

Where: isrc is the INTEGER*2 quantity to be converted. 

jres is the INTEGER*4 variable or array element 
which will receive the result. 



Function Results; 

i = -1 
= 
= 1 



Example: 



Normal return; the result is negative. 
Normal return; the result is zero. 
Normal return; the result is positive. 



INTEGER*4 JVAL 

CALL JICVT (478, JVAL) 



[FORM A 32-BIT CONSTANT 



JJCVT 



0.3.59 JJCVT 

The JJCVT function interchanges words of an INTEGER*4 value to form an 
internal format time or vice versa. This is necessary when the 
INTEGER*4 variable is to be used as an argument in a timer-support 
function such as ITWAIT. When a 2-word internal format time is 
specified to a function such as ITWAIT, it must have the high-order 
time as the first word and the low-order time as the second word. 

Form: CALL JJCVT (jsrc) 
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where: jsrc is the INTEGER*4 variable whose contents are 

to be interchanged. 

Errors : 

None . 

Example: 

INTEGER*4 TIME 



CALL GTIM(TIME) 
CALL JJCVT(TIME) 



!GET TIME OF DAY 

"TURN IT INTO INTEGER*4 FORMAT 




0.3. 60 JMOV 

The JMOV function assigns the value of an INTEGER*4 variable to 
another INTEGER*4 variable and returns the sign of the value moved. 

Form: i = JMOV (jsrc,jdest) 

where: jsrc is the INTEGER*4 variable whose contents are 

to be moved . 

jdest is the INTEGER*4 variable which is the target 
of the assignment. 

Function Result: 

The value of the function is an INTEGER*2 value which represents the 
sign of the result as follows: 



i = -1 
= 
= 1 



Normal return; the result is negative, 
Normal return; the result is zero. 
Normal return; the result is positive, 



Example ; 



The JMOV function allows an INTEGER*4 quantity to be compared with 
zero by using it in a logical IF statement, e.g., 

INTEGER*4 INT1 



IF(JM0V(INT1,INT1)) 300,100,300 !GO TO STMT 300 IF INT1 IS NOT 
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0.3.61 JMUL 

The JMUL function computes the product of two INTEGER*4 values. 

Forms i = JMUL ( joprl, jopr2 , jres) 

where joprl is an INTEGER*4 variable that is the 

multiplicand . 

jopr2 is an INTEGER*4 variable that is the 
multiplier . 

jres is an INTEGER*4 variable that receives the 
product of the operation. 

Function Results: 

i = -2 An overflow occurred while computing the result. 

= -1 Normal return; the product is negative. 

= Normal return; the product is zero. 

= 1 Normal return; the product is positive. 



Examplei 



INTEGER*4 J1,J2,JRES 



IF(JMUL(J1,J2,JRES)+1) 100,10,20 
C GOTO 100 IF OVERFLOW 
C GOTO 10 IF RESULT IS NEGATIVE 
C GOTO 20 IF RESULT IS POSITIVE OR ZERO 
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0.3.62 JSUB 

The JSUB function computes the difference between two INTEGER*4 
values. 

Form: i = JSUB ( jopr 1 , jopr2 , jres) 

where: joprl is an INTEGER*4 variable that is the minuend 

of the operation. 

jopr2 is an INTEGER*4 variable that is the 
subtrahend of the operation. 

jres is an INTEGER*4 variable that is to receive 
the difference between ioprl and iopr2 (i.e., 
jres= jopr l-jopr2) . 

Function Results: 

i = -2 An overflow occurred while computing the result. 

= -1 Normal return; the result is negative. 

= Normal return; the result is zero. 

= 1 Normal return; the result is positive. 

Example : 

INTEGER*4 JOPl,JOP2,J3 



CALL JSUB(JOPl,JOP2,J3) 
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0.3.63 JTIME 

The JTIME subroutine converts the time specified to the internal 
2-word format time. 

Form: CALL JTIME (hr s ,min , sec , tick , time) 

where: hrs is the integer number of hours. 

min is the integer number of minutes. 

sec is the integer number of seconds. 

tick is the integer number of ticks (1/60 of a 
second for 60-cycle clocks; 1/50 of a second 
for 50-cycle clocks) . 

time is the 2-word area to receive the internal 
format time: time(l) is the high-order 
time. time(2) is the low-order time. 

Errors : 

None . 

Example : 

INTEGER*4 Jl 



CONVERT 3 HRS, 7 MIN, 23 SECONDS TO INTEGER *4 VALUE 
CALL JTIME(3,7,23,0,J1) 
CALL JJCVT(Jl) 
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0.3.64 LEN 

The LEN function returns the number of characters currently in the 
string contained in a specified array. This number is computed as the 
number of characters preceding the first null byte encountered. If 
the specified array contains a null string, a value of zero is 
returned. 



Form: i = LEN (a) 
where: a 



specifies the array containing the string; 
must not be a quoted-str ing literal. 



Errors : 
None. 
Example : 



LOGICAL*! STRNG(73) 



TYPE 99, (STRNG(I) , 1=1 , LEN (STRNG) ) 
99 FORMAT) '0 ' ,132Al) 




0.3.65 LOCK 

The LOCK subroutine is issued to "lock" the USR in memory for a series 
of operations. The USR (User Service Routine) is the section of the 
RT-11 system which performs various file management functions. 
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If all the conditions which cause swapping are satisfied, a portion of 
the user program is written into scratch blocks and the USR is loaded. 
Otherwise, the USR which is in memory is used, and no swapping occurs. 
The USR is not released until an UNLOCK (see Section 0.3.88) is given. 
(Note that in an F/B System, calling the CSI may also perform an 
implicit UNLOCK.) A program which has many USR requests to make can 
LOCK the USR in memory, make all the requests, and then UNLOCK the 
USR; no time is spent doing unnecessary swapping. 

In an F/B environment, a LOCK inhibits the other job from using the 
USR. Thus, the USR should be locked only as long as necessary. 

Form: CALL LOCK 

Note that the LOCK routine reduces time spent in file handling by 
eliminating the swapping of the USR. If the USR is currently 
resident, LOCK involves no I/O. After a LOCK has been executed, the 
UNLOCK routine must be executed to release the USR from memory. The 
LOCK/UNLOCK routines are complementary and must be matched. That is, 
if three LOCKS are issued, at least three UNLOCKS must be done, 
otherwise the USR will not be released. More UNLOCKS than LO.CKs may 
occur without error; the extra UNLOCKS are ignored. 



Notes : 



1. It is vital that the LOCK call not come from within the area 
into which the USR will be swapped. If this should occur, 
the return from the USR request would not be to the user 
program, but to the USR itself, since the LOCK function 
causes part of the user program to be saved on disk and 
replaced in memory by the USR. Furthermore, subroutines, 
variables, and arrays in the area where the USR is swapping 
should not be referenced while the USR is LOCKed in memory. 

2. Once a LOCK has been performed, it is not advisable for the 
program to destroy the area the USR is in, even though no 
further use of the USR is required. This causes 
unpredictable results when an UNLOCK is done. 

3. LOCK cannot be called from a completion or interrupt routine. 

4. If a SET USR NO SWAP command has been issued, LOCK and UNLOCK 
will not cause the USR to swap but, in F/B, LOCK will still 
inhibit the other job from using the USR and UNLOCK will 
allow the other job access to the USR. 

5. Argument lists, such as device file name specifications, 
being passed to the USR must not be in the area into which 
the USR has just been locked. 



Errors ; 
None. 
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0.3.83 SUSPND (F/B Only) 

The SUSPND subroutine suspends main program execution of the current 
job and allows only completion routines (for I/O and scheduling 
requests) to run. 



Form : 



CALL SUSPND 



Notes : 



The monitor maintains a suspension counter for each job. 
This count is decremented by SUSPND and incremented by RESUME 
(see Section 0.3.77). A job will actually be suspended only 
if this counter is negative. Thus, if a RESUME is issued 
before a SUSPND, the latter function will return immediately. 

A program must issue an equal number of SUSPNDs and RESUMES. 



A RESUME subroutine call from the main program or 
completion routine increments the suspension counter. 



from 



4. A SUSPND subroutine call from a completion routine decrements 
the suspension counter but does not suspend the main program. 
If a completion routine does a SUSPND, the main program 
continues until it also issues a SUSPND, at which time it is 
suspended and will require two RESUMES to proceed. 

5. Because SUSPND and RESUME are used to simulate an ITWAIT (see 
Section 0.3.49) in the monitor, a RESUME issued from a 
completion routine and not matched by a previously executed 
SUSPND may cause the main program execution to continue past 
a timed wait before the entire time interval has elapsed. 

For further information on suspending main program execution of the 
current job, see the assembly language .SPND request, Section 9.4.39. 

Errors : 

None . 
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Example: 



INTEGER IAREA(4) 

COMMON /RDBLK/ IBUP(256) 

EXTERNAL RDFIN 



C 
C 
C 



IF(IREADF(256, IBUF , IBLK , ICHAN , IAREA , RDFIN) .NE.O) GOTO 1000 
GOTO 1000 FOR ANY TYPE OF ERROR 

DO OVERLAPPED PROCESSING 



CALL SUSPND "SYNCHRONIZE WITH COMPLETION ROUTINE 



END 



SUBROUTINE RDFIN (IARG1 , IARG2) 
COMMON /RDBLK/ IBUF (256) 



CALL RESUME "CONTINUE MAIN PROGRAM 



END 



TIMASC 



0.3.84 TIMASC 

The TIMASC subroutine converts a 2-word internal format time into an 
ASCII string of the form: 



hh:mm:ss 
where: hh 

mm 
ss 



is the 2-digit hours indication 
is the 2-digit minutes indication 
is the 2-digit seconds indication 



Form: CALL TIMASC ( itime ,strng) 
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where: itime is the 2-word internal format time to be 

converted. itime (1) is the high-order time, 
itime (2) is the low-order time. 

strng is the 8-element array to contain the ASCII 
time . 

Errors: 

None . 

Example : 

The following example determines the amount of time until 5 p.m. and 
prints it. 

INTEGER*4 J1,J2,J3 
LOGICAL*! STRNG (8) 



CALL JTIME(17,0,0,0,J1) 
CALL GTIM(J2) 
CALL JJCVT(Jl) 
CALL JJCVT(J2) 
CALL JSUB(J1,J2,J3) 
CALL JJCVT(J3) 
CALL TIMASC(J3, STRNG) 
TYPE 99, (STRNG(I) ,1=1,8) 
99 FORMAT (' IT IS ',8A1,' TILL 5 P.M.') 




0.3.85 TIME 

The TIME subroutine returns the current system time-of-day as an 
8-character ASCII string of the form: 

hh :mm:ss 

where: hh is the 2-digit hours indication 

mm is the 2-digit minutes indication 

ss is the 2-digit seconds indication 
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Form: CALL TIME (strng) 

where: strng is the 8-element array to receive the ASCII 

time . 

Notes : 

A 24-hour clock is used, e.g., 1:00 p.m. is represented as 13:00:00. 

Errors: 

None . 

Example : 

LOGICAL*! STRNG (8) 



CALL TIME (STRNG) 
TYPE 99, (STRNG(I) ,1 = 1,8) 
99 FORMAT (' IT IS NOW ',8A1) 
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0.3.86 TRANSL 

The TRANSL routine performs character translation on a specified 
string. The TRANSL routine requires approximately 64 words on the R6 
stack for its execution. This space should be considered when 
allocating stack space. 

Form: CALL TRANSL ( in ,out ,r { ,p }) 

where: in is the array containing the input string. 

out is the array to receive the translated 
string . 

r is the array containing the replacement 
string . 

p is the array containing the characters in 
"in" to be translated. 

The string specified by array "out" is replaced by the string 
specified by array "in", modified by the character translation process 
specified by arrays "r" and "p". If any character position in "in" 
contains a character which appears in the string specified by "p" , it 
is replaced in "out" by the corresponding character from string "r". 
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If the array "p" is omitted, it is assumed to be the 127 7-bit ASCII 
characters arranged in ascending order, beginning with the character 
whose ASCII code is 001. If strings "r" and "p" are given and differ 
in length, the longer string is truncated to the length of the 
shorter. If a character appears more than once in string "p" , only 
the last occurrence is significant. A character may appear any number 
of times in string "r". 

Errors : 

None . 

Examples: 

The following example causes the string in array A to be copied to 
array B. All periods within A become minus signs, and all question 
marks become exclamation points. 

CALL TRANSL(A,B, '-! ','.?' ) 

The following is an example of TRANSL being used to format character 
data . 

LOGICAL*l STRING(27) ,RESULT(27) ,PATRN(27) 
C SET UP THE STRING TO BE REFORMATTED 
C 

CALL SCOPY('THE HORN BLOWS AT MIDNIGHT ', STRING) 
C 

C 00000000011111111112222222 
C 12345678901234567890123456 
C THE HORN BLOWS AT MIDNIGHT 

C NOW SET UP PATRN TO CONTAIN THE FOLLOWING PATTERN: 

C 16,17,18,19,20,21,22,23,24,25,26,15,1,2,3,4,5,6,7,8,9,10,11,12,13,14,0 
C 

DO 10 1=16,26 
10 PATRN(I-15)=I 

PATRN(12)=15 

DO 20 1=1,14 
20 PATRN (I+12)=I 

PATRN (27)=0 
C 

C THE FOLLOWING CALL TO TRANSL REARRANGES THE CHARACTERS OF 
C THE INPUT STRING TO THE ORDER SPECIFIED BY PATRN: 
C 

CALL TRANSL(PATRN, RESULT, STRING) 
C 

C RESULT NOW CONTAINS THE STRING 'AT MIDNIGHT THE HORN BLOWS' 
C IN GENERAL, THIS METHOD CAN BE USED TO FORMAT INPUT STRINGS 
C OF UP TO 127 CHARACTERS. THE RESULTANT STRING WILL BE 
C AS LONG AS THE PATTERN STRING (AS IN THE ABOVE EXAMPLE) . 
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0.3.87 TRIM 

The TRIM routine shortens a specified character string by removing all 
trailing blanks. A trailing blank is a blank that has no non-blanks 
to its right. If the specified string contains all blank characters, 
it is replaced by the null string. If the specified string has no 
trailing blanks, it is unchanged. 

Form: CALL TRIM (a) 



where : 



is the array 
trimmed . 



containing the string to be 



Errors : 
None . 
Example : 



L0GICAL*1 STRING (81) 
ACCEPT 100, (STRING(I) ,1=1,80) 
100 FORMAT (80A1) 

CALL SCOPY (STRING, STRING, 80) 
CALL TRIM (STRING) 



IMAKE ASCIZ 

•TRIM TRAILING BLANKS 



UNLOCK 



0.3.88 UNLOCK 

The UNLOCK subroutine releases the User Service Routine (USR) from 
memory if it was placed there by the LOCK routine. If the LOCK 
required a swap, the UNLOCK loads the user program back into memory. 
If the USR does not require swapping, the UNLOCK involves no I/O. 
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Form: CALL UNLOCK 
Notes: 

1. It is important that at least as many UNLOCKS are given as 
LOCKS. If more LOCKs were done, the USR remains locked in 
memory. It is not harmful to give more UNLOCKS than are 
required; those that are extra are ignored. 

2. When running two jobs in the F/B system, use the LOCK/UNLOCK 
pairs only when absolutely necessary. If one job LOCKs the 
USR, the other job cannot use the USR until it is UNLOCKed. 
Thus, the USR should not be LOCKed unnecessarily, as this may 
degrade performance in some cases. 

3. In an F/B System, calling the CSI (ICSI) with input coming 
from the console terminal performs an implicit UNLOCK. 

For further information on releasing the USR from memory, see the 
assembly language .LOCK/. UNLOCK requests, Section 9.4.20. 

Errors : 

None . 

Example : 



GET READY TO DO MANY USR OPERATIONS 
CALL LOCK ! DISABLE USR SWAPPING 
PERFORM THE USR CALLS 



FREE THE USR 
CALL UNLOCK 



VERIFY 



0.3.89 VERIFY 

The VERIFY routine determines whether each character of a specified 
string occurs anywhere in another string. If a character does not 
exist in the string being examined, VERIFY returns its character 
position in string "b" . If all characters exist, VERIFY returns a 
zero . 
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Form: CALL VERIFY (a,b,i) 

or 

i = IVERIF (a,b) 

where: a is the array containing the string to be 

scanned . 

b is the array containing the string of 
characters to be accepted in a. 



is the integer result of the verification, 



Notes: 



Quoted-string literals must not be used with the IVERIF function 
subprogram. They may be used with the VERIFY subroutine subprogram. 

Function Result: 

i = if all characters of "a" exist in "b"; also if 

"a" is a null string. 
= n where n is the character position of the first 
character in "a" that does not appear in "b"; if 
"b" is a null string and "a" is not, i equals 1. 



Example : 

The following example accepts a 1- to 5-digit unsigned decimal number 
and returns its value. 

LOGICAL*! INSTR(81) 



CALL VERIFY (INSTR (IPOS) ,'0123456789' ,1) 
IF(I.EQ.l) STOP 'NUMBER MISSING' 
IF(I.EQ.O) I=LEN (INSTR) -IPOS+1 
IF(I.GT.5) STOP 'TOO MANY DIGITS' 
NUM=IVALUE (INSTR(IPOS) ,1) 



END 

FUNCTION I VALUE (ARRAY, I) 
LOGICAL*l ARRAY (1) 
DECODE (I, 99, ARRAY) IVALUE 
99 FORMAT (I 5) 
END 
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ERROR MESSAGE SUMMARY 



The information that formerly appeared in this appendix has now been 
incorporated into the RT-11 System Message Manual , DEC-11-0RMEA-A-D. 
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Absolute address 



Absolute block numbers 



A binary number that is assigned as the 
address of a fixed memory storage 
location. 

Any blocks which use block of a physical 
device as a base. Relative blocks use the 
start of a file as a base. 



Absolute section 



That portion of a program in which the 
programmer specifies the physical 
(absolute) locations of data items, using 
the .ASECT assembler directive. 



Addressing mode 



Allocation 

Alphanumeric character 
string 



The portion of a PDP-11 machine 
instruction which specifies how the 
argument is to be referenced. 

Assigning a resource to a job. 

A command string containing any of the 26 
alphabetic characters A-Z, the numeric 
characters 0-9, space and certain special 
characters . 



Argument 



A variable or constant which is given in 
the call of a subroutine as information to 
it; a variable upon whose value the value 
of a function depends; the known 
reference factor necessary to find an item 
in a table or array (i.e., the index). 



Argument block 



A block of memory 
programmed request 
monitor . 



used to transmit 
arguments to the 



Array 



ASCII 



A set or list of elements, usually 
subscripted variables or data. 

American Standard Code for Information 
Interchange. Established by American 
National Standards Institute to 
standardize a binary code for alphanumeric 
characters . 



Assembler 



Assembler directives 



A program that translated symbolic opcodes 
into machine language and assigns memory 
locations for variables and constants. 

The mnemonics used in the assembly 
language programs to control or direct the 
assembly process. 
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Assembly language 



A symbolic language that translates 
directly into machine language 
instructions. Usually there is a 
one-to-one relation between assembly 
language instructions and machine language 
instructions . 



Asynchronous 



Pertaining to the scheduling of 
hardware operations by ready and done 
signals rather than by time intervals. 

Pertaining to the method of data 
transmission in which each character 
is sent with its own synchronizing 
information. 



Autoincrement mode 



Background program 



Mode of operation wherein the contents of 
the register are incremented immediately 
after being used as the address of the 
operand . 

A program operating automatically, under 
low priority, when higher priority 
(foreground) programs are not using system 
resources . 



Backup file 



Bad blocks 



A copy of a file created for protection in 
case the primary file is inadvertently 
destroyed . 

A defective block of storage on any type 
of magnetic storage medium that produces a 
hardware error when attempting to read or 
write in the block. 



Base address 



A given address from which an absolute 
address is derived by combination with a 
relative address. An address constant. 



Base segment 



The portion of an overlayed program that 
is always memory resident; same as root 
segment. 



Baud 



Binary 



A unit of signaling speed. In a code in 
which all characters have the same length, 
one baud corresponds to a rate of one 
signal element per second, usually one bit 
per second. 

Pertaining to the number system having a 
oase or radix of two. In this system 
numbers are represented by Is and Os. 
Counting to ten in binary: 1, 10, 11, 
100, 101, 110, 111, 1000, 1001, 1010. 
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Bit 



Block-replaceable 
Blocks 



Bootstrap 

Bottom address 

Bounds 
Breakpoint 

Buffer 



Contraction of "Binary digit", a bit is 
the smallest unit of information in a 
binary system of notation. It is the 
choice between two possible states, 
usually designated one (1) and zero (0). 

See Random -Access. 

A set of consecutive machine words, 
characters or digits handled as a unit, 
particularly in reference to I/O. Each 
type of mass storage has its own block 
size, its own smallest unit of storage 
(e.g., PDP-11 DECtape has 256 
(decimal) 16-bit words per block) . See 
Data Block. 

A program whose purpose is to load and 
(usually) start a complex system of 
programs. 

The lowest memory address in which a 
program is located. 

The limits a program may operate within. 

A preset point in a user program where 
control passes to a debugging routine. 

A temporary storage area which may be a 
special register or an area of storage. 
Buffers are often used to hold data being 
passed between processes or devices which 
operate at different speeds or different 
times. 



Byte 



Carry bit 



Central processing unit 



Chaining 



Channel number 



A group of binary digits usually operated 
upon as a unit; 8 bits is usually a byte 
(1/2 a PDP-11 word) . 

A bit in the program status word 
indicating a carry from the most 
significant bit in the operation; also a 
common method of indicating a program 
request failure. 

The part of the computer containing the 
Arithmetic and Logical Unit, the 
Instruction Control Unit, timing 
generators and I/O interfaces of the basic 
system. 

A programming technique which involves 
dividing a routine into sections with each 
section terminated by a call to the next 
section . 

Logical identifier in the range to 255 
(decimal) assigned to a file used by RT-11 
monitor. Data blocks in an open file may 
be referred to by channel number. 
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Channnel status word 



Character-oriented 



Checksum 



Clock 



Closed location 



Co-resident overlay 
routines 

Command string 



Command String 
Interpreter 



Completion routine 
Compress 

Concatenate 
Condition codes 

Configuration 

Console device 



A word associated with each I/O channel in 
RT-11 that perserves the status of that 
channel . 

Referring to editing operations on a 
single character. See also Line-oriented. 

A value representing the sum of all bytes 
in a program, when the program is loaded, 
the sum of the bytes can be compared with 
the checksum to make sure that the entire 
program has been loaded correctly. 

A time-keeping or frequency-measuring 
device within the computer system. 



A location whose contents are 
available for examination and change, 



not 



Constant register 



Overlay routines that are simultaneously 
resident in memory. 

A series of characters which specify the 
input/output devices, files, and switches. 

The portion of the RT-11 system software 
which accepts an ASCII string input and 
interprets the string as input and output 
files and switches. 

An optional user-supplied routine that is 
called at the completion of an operation 
and is generally used to allow the user to 
handle asynchronous events. 

To collect into one area all the free 
(unused) blocks that are interspersed in 
the directory and files on a specified 
device. 

To combine many files into one file. 

The four bits of the Program Status Word 
in the PDP-11 Processor that preserve the 
results (negative, zero, carry, overflow) 
of the instruction just completed. 

A particular selection of computer, 
peripherals, and interfacing equipment 
that are functioning together. A list of 
the devices of a computer system. 

The interface, or communication device, 
between the operator and the computer, 
that contains indicator lights, switches, 
knobs and sometimes a keyboard to permit 
manual operation of the device. 

A logical register in ODT or PATCH that is 
used to store an often-used constant. 
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Context switching 



Contiguous 



Control Section (CSECT) 



Control statement 



Core memory 



Cross reference table 
(CREF) 



Cursor 
Data block 

Data format 

Data image 

Debug 
Default 

Delimiter 

Device block 



The saving of key registers and other 
memory areas prior to switching between 
jobs, as in timesharing or 
multiprogramming . 

Code that resides in memory or on a 
peripheral device immediately adjacent to 
other sections of code or data. 

A named, contiguous part of a program. 
CSECTs are denoted by the directives 
".CSECT" and " .ASECT" in the MACRO 
Assembler Language. CSECTs are collected 
and assigned addresses by the Linker. 

A job statement that is used to issue 
commands to the system through the input 
stream. 

The main high-speed storage of a computer 
in which binary data is represented by the 
switching polarity of magnetic cores. 
Semi-conductor memory is higher speed than 
core memory, but semi-conductor memory is 
more expensive and volatile. 

A list of all or a subset of symbols in 
source program and statements where they 
were defined or used. 

On a display device, a symbol that appears 
to indicate the location of the pointer. 

A logical grouping of data, usually 
associated with input or output. Typical 
data block involved in RT-11 are 256 words 
long . 

The form or structure of information, 
particularly in an I/O file. RT-11 has 
several standard data formats such as 
ASCII and formatted binary. 

A job statement that is used to define 
data for system programs and user programs 
through the input stream. 

To detect, locate, and correct mistakes in 
a program. 

A specification assigned by a system 
program when user specification is 
omitted . 

A character that separates, terminates and 
organizes elements of a statement or 
program. 

A section of code that specifies a 
physical device and filename for an RT-11 
programmed request. 
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Device directory 
listing 



Device handlers 



Direct assignment 

Directive 
Directory 

Disk 



Display unit 



Double buffered I/O 



Dummy file 
Ed i to r 



EMT 



Entry point 



A list of all files on a specified device. 
The list contains all files with 
associated creation dates, total free 
blocks on the device, and number of blocks 
used by files. Magtape and cassette 
directories omit some information. See 
Directory. 

Routines that perform I/O for specific 
storage devices and translate logical 
block numbers to physical disk, tape or 
drum addresses. These routines also 
handle error recovery and provide device 
independence in conjunction with operating 
systems. 



User definition of 
associated value. 



a symbol and its 



See Assembler directives. 

An area of a mass storage device that 

describes the layout of the data on that 

device in terms of file names, length and 
location. 

A mass storage device. Basic unit is an 
electromagnetic platter on which data is 
magnetically recorded. Features random 
access and faster access time than 
magnetic tape. 



A device that provides 
representation of data. 



visual 



An input (or output) operation using two 
buffers to achieve more efficient usage of 
computer time. While one buffer is being 
used by the CPU program, the other is 
being read from (or written to) by an I/O 
device . 



A file used only 
storage device. 



to hold space on a 



A program which interacts with the 
programmer to enter new programs into the 
computer and edit them as well as modify 
existing programs. Editors are language 
independent and will edit anything in 
alphanumeric representation. 

A PDP-11 machine instruction (operation 
codes from 104000-1043777). EMTs are most 
often used for monitor communication. 



A point in a subroutine to 
is transferred when the 
called . 



which control 
subroutine is 
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Entry point table 



Entry symbol 



Error flag 



Exception 
Expressions 

External symbol 



Fatal error 



A table, kept by the Librarian program, of 
the names and locations of the routines 
available in the library. 

A global symbol defined in an object 
module that can be referred to by other 
object module. 

Condition indicating an error has 
occurred. If the C bit is set on return 
from an RT-11 call, an error occurred. 
Thus, the C bit set is the RT-11 error 
flag . 

An unusual condition (e.g., a floating 
point exception is an overflow) . 

A combination of variables, constants, and 
operators (as in a mathematical 
expression) . 

A symbolic name which is defined in one 
assembly or compilation and can be 
referenced in another. The .GLOBL 
directive is used to indicate external 
symbols to the MACRO assembler . 

An error which makes continued processing 
impossible (e.g., running out of symbol 
table space is usually a fatal error) . 



File allocation scheme 



The method 
devices . 
structure . 



used to store data on I/O 
RT-11 uses a contiguous 



File gap 



File-structured device 



Filler characters 



Flag 



Floating-point 



A fixed length of blank tape separating 
files on a recording medium. 

A device on which data is given names and 
arranged in files (e.g., disk, DECtape, 
magtape, or cassette) . 

Null characters output to a device to give 
it time to perform unusually long 
operations (such as return the carriage) 
without explicitly waiting. 

A variable or register used to record the 
status of a program or device. In the 
latter case it is sometimes called a 
device flag. 

A number system in which the position of 
the radix point is indicated by one part 
(the exponent part) , and another part 
represents the significant digits, the 
fractional part (e.g., 5.39X10(8) for 
Decimal; 137.3X8(4) for Octal; 
101.10X2(13) for Binary). 
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Foreground program 



Formatted binary block 



Fragmented 
Free blocks 
General registers 



Global symbol 

Global symbol directory 

Handler 
Hardware mode 

High level language 

Image mode 
Implied argument 

Indexing 
Initialize 



A program of high priority that utilizes 
machine facilities when and as needed, but 
allows less critical background work to be 
performed in otherwise unused time. 

A data structure used to hold binary 
information, usually to be read or written 
to a data file. For example, an object 
module produced by the MACRO assembler 
consists of formatted binary blocks. 

Having many empty entries scattered over a 
device. 

Areas of a file structured device which 
are unused . 

A set of eight general purpose registers 
available for use as accumulators, as auto 
index registers or as pointers. General 
registers 6 and 7 serve as the hardware 
stack pointer and program counter 
respectively. 

Any symbol accessible to other programs. 
Linkage must be supplied by a linker. 

The portion of an object module which 
describes all external symbols and CSECT 
names which are defined or referenced by 
the object module. 

See Device handler 

For magnetic tapes and cassettes. Allows 
full user control over position and record 
size (as opposed to software mode.) 

A language in which single statements may 
result in more than one machine language 
instruction, e.g., BASIC, FORTRAN, COBOL. 

A mode of data transfer in PIP in which a 
file is copied without change of any kind. 

An argument which is assumed by the 
program, whether or not it is explicitly 
stated by the user. 



Using a variable index register as 
offset into a table. 



an 



To set counters, switches, addresses and 
variables to zero or other starting 
values. 
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Input stream 



Internal symbol 



Interrupt service routine 



Interrupt 



The sequence of control statements and 
data images submitted to the operating 
system on an input device especially 
dedicated for this purpose. 

A symbolic name which is known only within 
the assembly or compilation where it is 
defined. Symbols are internal by default. 

Routine entered when an external interrupt 
occurs. 

1. To break the normal operation of the 
routine being executed and pass 
control to a specific location, 
generally accompanied by saving the 
state of the current routine so that 
control can return later. 



Iterations 
Job 



Job status word 

Keyboard monitor (KMON) 

Keyword 
Label 

LDA format file 
Library 

Library header 



Light pen 



2. The signal which causes the break. 

Repetitions of a portion of a program. 

The largest definable collection of 
elements describing the work to be 
performed. The purpose of the job is to 
collect and describe the logical work 
which is to be performed. A job is 
composed of control statements and data 
images. 

A word in the RT-11 communications region 
containing bit flags indicating the status 
of the program currently in memory. 

The program that provides communication 
between the user at the console and the 
RT-11 system. 

A symbol that identifies a parameter. 

One or more characters used to identify a 
source language statement or line. 

See Load image file. 

A collection of standard routines which 
can be incorporated into other programs. 

Section of code that contains the current 
status of the library, including version, 
date and time of creation or update, 
relative starting address of entry point 
table, number of EPT entries and placing 
of next module to be inserted into the 
library file. 

A device resembling a pencil or stylus 
which can detect a fluorescing spot on a 
CRT screen. Used to input information to 
a CRT display system. 
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Line-oriented 



Referring to editing operations on an 
entire line of text. See also 
Character-oriented . 



Load image file 



A program that can be executed in 
stand-alone environment without the aid of 
relocation . 



Local symbol 



A symbol used only within the program in 
which it is defined (all non-global 
symbols) . 



Location counter 



Logical name 



A counter kept by an assembler to 
determine the address assigned to an 
instruction or constant being assembled. 

A user-defined name assigned as an 
alternate name for a physical device. 
Useful for redirecting I/O when device 
originally specified is unavailable. 



Loop 



A sequence of instructions that is 
executed repeatedly until a terminal 
condition occurs. Also, used as a verb 
meaning to execute this circle of 
instructions while waiting for the ending 
condition . 



Macro 



Macro symbol 



An instruction in a source language that 
is equivalent to a specified sequence of 
machine instructions, or a command in a 
command language that is equivalent to a 
specified sequence of commands. 



Symbol used as 
field. 



macro name in operator 



Mainstream code 



Mask word 



Any code which is not executing as a 
result of a completion routine. 

A combination of bits that is used to 
access selected portions of any word, 
character, byte, or register while 
retaining other parts for use. Also, to 
clear these selected locations with a 
mask . 



Memory address 
Memory image 



An address in memory used to store data. 

An exact copy of a portion of memory. 
RT-11 save image files (.SAV) are memory 
images. 



Mnemonic 



Alphabetic representation of a function or 
octal machine instruction. 



Mode 



A state or method of program operation. 
Command mode causes user input to be 
interpreted as a command; text mode 
causes user input to be interpreted as 
alphanumeric data, etc. 



GLOSSARY- 10 



GLOSSARY 



Module 



Monitor 



A routine 
function . 



which handles a particular 



Monitor System 



Multi-region 



Nesting 



Nonfile- structured 
device 



Nonf ile-structured 
.LOOKUP (or .ENTER) 



NonRT-11 directory- 
structured 



Null 
Object code 

Off-line 

Offset 
On-line 

Open location 



The collection of routines which schedules 
resources, I/O, system programs, and user 
programs, and obeys keyboard commands in a 
Monitor System. 

Editors, assemblers, compilers, loaders, 
interpreters, data management programs and 
other utility programs all automated for 
the user by a monitor. 

A term describing the RT-11 overlay 
structure in which there may exist 
multiple independent areas of high-speed 
memory (regions) in which overlays may 
occur . 

1. Including a program loop inside 
another program loop, or other similar 
occurrences within one another. 

2. Algebraic nesting such as (A+B+(C+D)) 
where execution proceeds from the 
innermost level to the outermost 
level . 

A device that is used only for input or 
output, and not storage, of a file (e.g., 
line printer, card reader, terminal, or 
paper tape). 

A .LOOKUP (or .ENTER) with a null file- 
name, that permits access to a device by 
reference to absolute block numbers, 
rather than block numbers relative to a 
file. 

A device having no standard RT-11 
directory at its beginning. This includes 
magtape and cassette, and any devices for 
which user-defined directories have been 
written. 

Characters with ASCII code 000. 



The result after assembling 
source code. Machine code. 



or compiling 



Pertaining to equipment, devices or events 
which are not under direct control of the 
computer . 



The difference between a location 
interest and some known base location. 



of 



Pertaining to equipment, devices and 
events which are in direct communication 
with the CPU and thereby under its control 
in some way. 

A location whose contents have been 
printed for examination; contents can be 
changed . 



GLOSSARY- 11 



January 197 6 



GLOSSARY 



Operand 



Operating system 



Operator 



Output stream 



Overlay 



Overlay segment 



Overlay-structured 



Page of text 



Parameter 



Patch 

Peripheral devices 

Permanent file 
Permanent symbol 



A quantity which is affected, 
manipulated or operated upon. 



The contents of 
the operator 
instruction. 



the field 
of an 



following 
assembler 



A program for automating a programmer's 
use of software. A Monitor System. 



That symbol or code which indicates 
action or operation to be performed. 



an 



Output data issued by the operating system 
on the processing program to an output 
device especially designated for this 
purpose . 

The technique of repeatedly using the same 
area of memory during different stages of 
a program. When one routine is no longer 
needed in memory, another routine can 
replace all or part of it. Over-laying 
replaces parts of programs; chaining 
replaces the whole program. 

A section of code handled as a unit. This 
segment of code can overlay code already 
in memory or can be overlaid by another 
overlay segment. 

A term describing a program which does not 
entirely reside in high-speed memory at 
any instant. Portions of the program are 
brought into memory when needed. 

That portion of a file delimited by form 
feed characters, generally 50-60 lines 
long: corresponds approximately to a 
physical page of program listing. 

A variable or an arbitrary constant 
appearing in a mathematical expression, 
each value of which restricts or 
determines the specific form of the 
expression . 

To modify a routine in a rough or 
expedient way, usually by modifying the 
binary code rather than reassembling it. 

In a data processing system, any device 
distinct from the central processing unit,, 
which may provide the system with outside 
storage or communication. 



An output file that is 
for later use. 



stored in memory 



Instruction mnemonics, assembler 
directives, and macro directives 
incorporated in the assembler. 
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Physical device 



Physical name 



PIC code 



Pointer 



Positional parameter 



Proceed count 



Processor status register 



Program counter 



Program sections 
Programmed requests 

Purge 
Rad ix 

Random- access 



An input, output, or storage device 
associated with the Central Processing 
Unit. 

A 2- or 3-character name identifying a 
physical device. The first two characters 
are alphabetic and identify the device; 
the third character is numeric and 
identifies the unit. 

Abbreviation for Position Independent 
Code. (Code which can operate properly 
wherever it may be loaded in memory) . 

1. A location containing the address to 
another location. 

2. In the EDIT program, a movable 
reference pointer normally located 
between the character most recently 
operated upon and the next character 
in the buffer; represents the current 
position of the Editor in the text. 

A parameter that must appear in a 
specified position in an ordered group of 
parameters. 

In a program loop, the number of times the 
breakpoint is to be encountered before 
suspension of program execution. 

A register that indicates the current 
priority of the processor, the condition 
of the previous operation, and other basic 
control items. 

A register in the CPU that holds the 
address of the current instruction being 
executed plus two; in other words, it 
holds the address of the next instruction 
unless the current instruction causes a 
jump. 

See Control section. 

Machine language instruction which is used 
to invoke a monitor service for the 
issuing program. 

Deactivate a channel without taking any 
other action. 



The base of a number system; 
of digit symbols required 
system. 



the number 
by a number 



A means of accessing data in a random 
order (independently of the data's 
physical or relative position on the 
device) . 
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Real time 



Real time system 



Record 



Reentry address 



Region number 



Relative address 



Relocatable code 



1. Pertaining to the actual time during 
which a physical process takes place. 

2. Pertaining to the performance of 
computer activity which occurs fast 
enough to influence the related 
physical process. 

A system in which computation is performed 
while a related physical process is 
occurring so that the results of the 
computation can be used in guiding the 
physical process. 

A collection of related items of data 
treated as a unit. Example: A line of: 
source code. 

The Start address -2. Allows the user 
program to reset itself internally, and 
resume operation. 

A number which is used to identify a 
portion of memory to the Linker for the 
purpose of describing an overlay 
structure . 

A number specifying the difference between 
an absolute address and a base address. 

Code written so that it can be located and 
executed in any part of memory, once it 
has been linked by Linker. 



Relocatable object modules A set of instructions which are written so 

that the module can be loaded and executed 
in any memory area. 



Relocatable symbols 



Relocation 



Relocation directory 



Repeat block 



Repeat count 



Symbolic names whose associated value is 
an offset from the base (beginning) of a 
control section. Such a symbol's value 
depends on the address of the control 
section and must be relocated each time 
the control section is assigned an address 
by the Linker. 

To move a routine from one portion of 
storage to another and to adjust the 
necessary address references so that the 
routine can be executed in the new 
location. 

A portion of an object module which 
describes and identifies all occurrences 
of relocatable symbols in the object 
module . 

Block of code to be repeated a defined 
number of times. 

The number of times a block of code is to 
be repeated. 
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Resident 



Resident monitor (RMON) 



In memory, as opposed to being stored 
externally. 

The permanent memory-resident part of 
RT-11. Contains console terminal service, 
the error processor, the system device 
handler, the EMT processor, and system 
tables . 



Root segment 

RT-11 directory- 
structured 



Scratch area 



Scrolling 



See Base segment. 

A device having a standard RT-11 directory 
at its beginning that is updated as files 
on the device are manipulated (for 
example, disk and DECtape) . 

Any memory or registers used for temporary 
storage of partial results. 

On a display screen, when the maximum 
number of lines are on the screen, the top 
line is deleted, and all text moves up one 
line, permitting one new line of display 
at the bottom of the screen. The visual 
effect is similar to the rolling up of a 
scroll . 



Sentinel file 



Sequence number 



Sequential-access 



Software mode 



Source code 



The last file on cassette tape; contains 
only a header record and represents 
logical end-of-tape. 

The number in a cassette directory which 
designates where a file is placed (in 
sequence) , when that file has been 
continued on more than one cassette. 

A means of accessing data in which records 
or blocks are read one after another from 
the device (as opposed to random-access) . 

For magnetic tapes and cassettes, the mode 
of operation when device access is through 
any RT-11 system program. 

Text, usually in the form of an ASCII 
formatted file, which represents a 
program. Such a file can be processed by 
an appropriate system program (MACRO or 
FORTRAN) to produce an object module. 



Source file 



A file to be used 
translating program 
BASIC. 



as input to a 
such as MACRO or 



Stack 



An area of memory set aside by the 
programmer for temporary storage or 
subroutine interrupt service linkage. The 
stack uses the "last-in, first-out" 
concept. The stack starts at the highest 
location reserved for it and expands 
linearly downward as items are added to 
the stack. 
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Stack pointer 



Storage device 



Subconditionals 



Subpicture address 



Suspend 



Swap 



Switch register 



Switches 



Symbols 



Symbol table 



A general register used to keep track of 
the last location where data is entered 
into the stack. 

A general term for any device capable of 
retaining information. 

Directives that indicate: 

1. assembly of an alternate body of code; 

2. assembly of a non-contiguous body of 
code within a conditional block; 

3. unconditional assembly of a body of 
code within a conditional block. 

Address of a set of display processor 
instructions which display text on a GT40 
(42,44) . 

To temporarily halt execution of a task 
while another task of different priority 
runs . 

The process of saving user memory in 
system device scratch blocks, reading in 
and executing a USR function, and then 
restoring the user code. 

A location in the CPU which can be loaded 
with a value by the operator by his 
setting switches on the computer console 
for each bit he wants to enter. 

1. in a command string to the CSI a 
switch is a slash followed by an ASCII 
character which can be given a value 
by typing a colon after the character 
followed by an octal number or from 
1-3 ASCII characters. 

2. Two or three position mechanisms used 
for operating computer or devices. 

Names which can be assigned values or 
which can be used to indicate specific 
locations in a program. 

An array which contains all defined 
symbols and the binary value associated 
with each one. Mnemonic operators, labels 
and user defined symbols are all placed in 
the symbol table. (Mnemonic operators 
stay in the table permanently.) 



System configuration 
System device 



See Configuration. 

A peripheral file-structured storage 
device on which the monitor resides. 
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System programs 

Time-critical job 

Transfer address 
Trap 



Truncation 



Two ' s c ompl emen t 



Type-ahead 

Unary operation 
User-defined sybmbol 

Utility 
Vector 

Wild card operation 
Word-for-word transfer 



DEC-supplied programs which come in the 
basic software packages. These include 
editors, PIP, assemblers, compilers, 
loaders, etc. 

A job which demands response within a 
fixed time period. 

A program entry point. 

1. An automatic transfer of control to a 
prespecified routine that can be 
caused by software or hardware. The 
trap instruction is an example of a 
hardware implementation. 

2. A conditional jump to a known location 
performed automatically by hardware as 
a side effect to executing a processor 
instruction. The address location 
from which the jump is made is 
recorded. It is distinguished from an 
interrupt which is caused by an 
external event. 

The reduction of precision by ignoring one 
or more of the digits (not rounding off) . 

A number used to represent the negative of 
a given value in many computers. This 
number is formed from the given binary 
value by changing all Is to Os and all Os 
to Is, and then adding 1. 

The ability to type information at the 
console terminal and have it remembered by 
the system for later use. 

Operation affecting a single operand. 
Examples: negation, radix indicator. 

1. A label; 

2. A symbol defined by direct assignment. 



Any program which performs 
functions, i.e., PIP. 



useful 



Two words describing 1) where to go when 
external interrupt occurs, and 2) the 
contents of the processor status word when 
the interrupt is acknowledged. 



A shorthand 
files with 
both. 



method of transferring all 
the same name, extension, or 



A transfer in which no alteration of data 
is performed. 
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Words 



Write-lock condition 



In the PDP-11 a 16-bit unit of data which 
may be stored in an addressable location. 

The condition of a device that is 
protected against any transfers which 
would write information to it. 



Zero 



To initialize a device (e.g., DECtape, 
cassette) so that it contains no 
information. 
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Abbreviating command names (BATCH) , 

12-3 
Abort entry point, 9-46, H-4 
Absolute, 5-3 

and relocatable program sections, 
6-4 

block numbers, 4-21, 1-2 

expression, 5-18, C-5 

load address, 6-1 

load module, 6-5 

mode, 5-24 

quantities, 5-17 

section, 6-4 

starting block, 4-17 
Absolute Loader, 6-5 
Absolute sectors, reading and 

writing, 9-85, H-13.2 
Accessing, 

general registers, 8-9 

internal registers, 8-10 
Add two INTEGER* 4 values, 0-88 
Additional and reference 

material, xxiii 
Address mode syntax, C-5 
Address specifier, M-2 
Addressed location, 8-8 
Addresses, vector, 9-6 
Addressing modes, 5-20 
Advance command, 3-17 
AJFLT function, 0-21 
Allocating, 

blocks for files, 4-11 

character string variables, 0-19 

extra words, 4-18 

memory for a queue, 9-66 

system resources, 2-16 

words, 2-36 
Alphabetize switch, 6-18 
Alphabetized load map, 6-19 
Alphanumeric representation, 1-2 
ALTMODE, 3-2 
Argument, 3-4 

block, 9-3 

CSECT, M-3 

dummy , 5-67 

iteration, 3-8 

list, 9-5 

list pointer, 9-2 

negative line, 3-7 

numeric, 3-6 

numerical, 9-4 

positive, 3-7 

substitution, 5-72 
Arguments, 9-2 

EDIT, 3-4 

indefinite repeat, 5-72 

missing, 5-66 

number of, 5-66 

real, 5-63 

symbolic, 5-37 



Arguments (cont.), 

to Macro calls and definitions, 
5-62 
ASCII, 

character set, C-l, C-4 

code, 0-18 

conversion of one or two 

characters, 5-40 
files, 3-1 
format, 2-3 

input and output, 8-20 
to Radix-50 conversion, 0-105 
.ASCII directive, 5-41 
.ASCIZ directive, 5-42 
.ASECT directive, 5-53, 6-4, 6-6 
.ASECTs, H-3 

ASEMBL (8K assembler), 1-4, 11-1 
calling and using, 11-1 
error messages, 11-7 
file specifications, 11-2 
Assembler, 1-2, 8-4 
ASEMBL, 11-1 
MACRO, 5-1, 12-29 
output, 5-19 
Assembler directives, 5-3, 5-27, 
C-19 
.ASCII, 5-41 
.ASCIZ, 5-42 
.ASECT, 5-53 
.BLKB, 5-47 
.BLKW, 5-47 
.BYTE, 5-38 
.CSECT, 5-53 
.DSABL, 5-36 
.ENABL, 5-36 
.END, 5-50 
.ENDM, 5-60 
.EOT, 5-51 
.ERROR, 5-70 
.EVEN, 5-46 
.FLT2, 5-48 
•FLT4, 5-48 
.GLOBL, 5-54 
•IDENT, 5-36 
.IFF, 5-57 
•IFT, 5-57 
.IFTF, 5-57 
.IRP, 5-71 
.IRPC, 5-72 
.LIMIT, 5-51 
.LIST, 5-27 
.MACRO, 5-60 
.MCALL, 5-74 
.MEXIT, 5-61 
.NARG, 5-68 
.NCHR, 5-68 
.NLIST, 5-27 
.NTYPE, 5-69 
.ODD, 5-46 
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Assembler directives (cont.)/ 
.PAGE, 5-36 

.PRINT, 5-71 

•RADIX, 5-44 

.RAD50, 5-43 

.REPT, 5-73 

•SBTTL, 5-34 

.TITLE, 5-34 

•WORD, 5-39 
Assembling graphics programs, N-16 
Assembly instructions, N-24 
Assembly, 

language completion routine, 
O-100 

language display support, N-l 

language routines, 0-5 

language statement, 5-2 

listing, 8-1 

listing table of contents, 5-35 

location counter, 5-14 

pass, 5-14 

source listing showing local 
symbol blocks, 5-15 
ASSIGN command, 2-18 
Asterisk, 

data line indicator, 12-3 8 

wild-card, 4-1, 12-7 
Asynchronous completion routines , 

9-13 
Autodecrement mode, 5-23 
Autodecrement deferred mode, 5-23 
Autoincrement mode, 5-21 
Autoincrement deferred mode, 5-22 
Automatic generation of local 

symbols, 5-13 
Automatic relocation facility, 8-4 
Automatically created symbols 
within user-defined Macros, 
5-66 



Backslash, 8-7 

Backup storage device, 6-10 

Back-arrow, 8-8 

Back space, H-ll, 0-72 

Bad block files, 4-2 

Bad block scan, 4-21 

Bad entry, 8-2, 8-26 

Base address, 5-25, 8-4 

Base command, 2-29 

Base segment, N-2 

$BASIC command, 12-13 

BASIC/GT subroutine structure, N-20 

BASIC/RT-11, 1-1, 1-5 

commands, F-3 

error messages, F-6 

function errors, F-9 

functions, F-5 

language, F-l 

language summary, F-l 

statements, F-l 

string functions, F-5 



BATCH, 1-5, 12-1 

character set, 12-8 

command field switches, 12-3 

command fields, 12-2 

command summary, B-17 

commands, 12-12, 12-36 

comment fields, 12-8 

control statement format, 12-2 

device names, 12-6 

differences between RT-11 BATCH 
and RSX-11D BATCH, 12-52 

error messages, 12-53 

example, 12-36 

filename extensions, 12-7 

file specifications, 12-6 

files, 12-10 

hardware requirements, 12-1 

operating procedures, 12-45 

operator directives, 12-50 

punched card programs, 12-44 

RT-11 mode, 12-38 

rules and conventions, 12-11 

software requirements, 12-2 

specification field switches, 12-8 

specification fields, 12-5 

switch summary, B-14 

wild card construction, 12-7 
BATCH commands, 

$BASIC, 12-13 

$CALL, 12-14 

$CHAIN, 12-15 

$C0PY, 12-16 

$CREATE, 12-18 

$DATA, 12-19 

$DELETE, 12-20 

$DIRECTORY, 12-20 

$DISMOUNT, 12-21 

$EOD, 12-22 

$EOJ, 12-23 

$FORTRAN, 12-23 

$JOB, 12-25 

$LIBRARY, 12-27 

$LINK, 12-27 

$MACRO, 12-29 

$MESSAGE, 12-31 

$MOUNT, 12-32 

$PRINT, 12-34 

$RT11, 12-35 

$RUN, 12-35 

$SEQUENCE, 12-36 
Beginning command, 3-16 
Binary, 

code, 1-2 

object module, 8-4 

operators, 5-8, 5-18 

output, 1-2 

radix, 5-17, 5-45 
Bit patterns, 1-3, 8-24 

search, 8-10 
.BLANK, N-3 
Blank COMMON, 6-14 
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Blank, 

extension filename, 2-7 
fields, 9-110 
lines, 5-2 
.BLKB directive, 5-47 
.BLKW directive, 5-47 
Blocks, 2-10 
control, 6-1 
device, 9-5 
EMT arguments, 9-5 
lengths, 4-4 
256-word, 2-32 
Block numbers, H-9 
absolute, 1-2 
physical, 1-2 
Block-replaceable devices, 2-7, 

2-36, 4-14 
Boot operation, 4-20 
Bootable magtape, 4-5 
Bootstrap , 

copy operation, 4-20 
file, 4-19 
manual, 2-2 
Bootstrapping the system, 4-20 
Bottom address switch, 6-18 
Branch, 

address, 5-26 

instruction addressing, 5-26 
instructions, 5-27, C-13 
Breakpoints, 8-11, 8-21 

table, 8-10, 8-13 
Buffer, 

flag, N-7, N-ll 
macro, 3-10 
save, 3-10 
structure, N-7 
text, 3-2, 3-21 
Building, 

a memory image, 2-28 
VTLIB.OBJ, N-26 
Byte, 8-7 

offset, 5-27 
BYTE command, M-3 

BYTE directive, 5-38 



Calculating offsets, 8-17 
$CALL command, 12-14 
Calling and using, 

ASEMBL, 11-1 

DUMP, 1-1 

EDIT, 3-1 

EXPAND, 10-2 

FILEX, J-l 

LIBR, 7-1 

LINK, 6-2 

MACRO, 5-7 4 

ODT, 8-1 

PATCH, L-l 

PATCHO, M-l 

PIP, 4-1 

SRCCOM, K-l 
Calling SYSLIB subprograms, 0-3 



Calls or branches to overlay 

segments, 6-13 
Cancel scheduling requests, 0-36 
Card, 

deck, 12-45 

input, 12-46 
Card codes, 2-24, H-6 

conversion table, H-25 
Card reader handler, H-6, 12-46 
Carriage control, 0-33 
Carry bit, 9-13 
Cassette, 

handler functions, 0-72 

rewind button, 4-7 

sequence number, 4-7 
Cassette special functions, H-12 

last block, H-12 

last file, H-12 

next block, H-12 

next file, H-12 

rewind, H-12 

write file gap, H-13 
Cassettes and magtapes, 

end-of-file detection, H-13 

initializing, 4-13 

legal operations, 4-5 
Cathode ray tube, N-l 
.CDFN request, 9-26 
Centralized queue management 

system, 9-65 
CHAIN bit, 9-8 
$CHAIN command, 12-15 
.CHAIN request, 9-27 
CHAIN subroutine, 0-22 
Chaining, 0-105 
Change command, 3-22 
Changing, 

device handler characteristics, 
2-23 

monitors, 2-2.1 

stack size, 2-36 
Channel, 9-41 

allocation, 0-34, 0-46 

assignment, 0-99 

data, 9-78 

deactivation, O-103 

number, 9-5, 0-47 

returned to pool, 0-45 

status, 0-39, 0-65 

status word, 9-13, 9-41, 9-78 
Channel-oriented operations, 0-9, 

0-17 
Channels, 9-35 
Chapter summary, xxi 
Character , 

deletion, 9-94 

substitution, 5-72 

transfer, 9-93 
Character- and line-oriented 

command properties, 3-6 
Character-oriented commands, 3-6 
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Character set, 5-5, 12-8, 12-9 

ASCII, C-4 

Radix-50, C-3 
Character string, 

comparison, O-108 

functions, 0-13, 0-18 

shortening, 0-18 
Character transfer, 

console terminal to user program, 
0-79 

user program to console terminal, 
0-81, O-102 
Character translation, 0-116 
Character verification, 0-119 
Characters, 

illegal, 5-7 

legal, 5-5 

operator, 5-8 

optional, 2-14 

prompting, 2-4 

special, 5-64 

upper-/lower-case, 3-27, 0-8 
.CHCOPY request, 9-28 
Checking channel status, 9-99 
Checksum, 4-9, M-4 , M-5 
.CLEAR, N-4 
Clearing breakpoints, restarting 

ODT, 8-2 
Clock, 2-17 

frequency, 9-52 

rate, 2-17, 9-52 

ticks, 9-51 
CLOSE command, 2-20 
CLOSE handler function, H-9 
.CLOSE request, 9-3 
CL0SEC subroutine, 0-23 
Closed location, 8-6 
Closing a channel, 0-23 
.CMKT request, 9-31 
.CNTXSW request, 9-32 



Code, 

binary, 1-2 

modifications, L-l 

object, 1-2 

source, 1-2 
Combining 

files, 4-9 

library switch functions, 7-11 
Command and Switch Summaries, B-l 
Command , 

arguments (EDIT) , 3-5, B-5 

continuation switch, 7-3 

decoder, 8-20 

execution routine, 8-21 

field, 12-2 

field switches, 12-3, 12-6 

interpretation services, 9-1 

mode, 3-2 

repetition, 3-8 

string format, 2-10 

string interpreter (SYSLIB) , 
0-37 

strings, 3-5, 6-2 

structure (EDIT) , 3-3 
January 1976 INDEX-4 



Command (cont. ) , 
switches, 4-1, K-2 
syntax (LIBR) , 7-2 
Command String Interpreter, 2-7, 

2-10, 6-3, 9-33, L-2 
Command summary, 
BATCH, B-17 
EDIT, B-5 

Keyboard monitor, B-l 
ODT, B-l 2 
PATCH, B-20 
PATCH0, B-21 
Commands, 

and functions, 8-5 
BASIC/RT-11, F-3 
BATCH, see BATCH commands 
character-oriented, 3-6 
control, 3-2 
display editor, 3-4 
edit control, 3-2 
input/output, 3-3, 3-10 
keyboard, 2-14 
line-oriented, 3-6 
PATCH, L-2 

pointer relocation, 3-16 
search, 3-18 

text modification, 3-4, 3-20 
utility, 3-4, 3-24 
Commands to allocate system 
resources, 2-16 
ASSIGN, 2-18 
CLOSE, 2-20 
DATE, 2-16 
INITIALIZE, 2-18 
LOAD, 2-20 
SET, 2-23 
TIME, 2-17 
UNLOAD, 2-23 
Commands to control terminal I/O, 
2-15 
GT OFF, 2-16 
GT ON, 2-15 
Commands to manipulate memory 
images, 2-28 
Base, 2-29 
Deposit, 2-30 
Examine, 2-30 
GET, 2-28 
SAVE, 2-31 
Commands used only in a F/B 
environment, 2-3 5 
FRUN, 2-36, 
RSUME, 2-38 
SUSPEND, 2-37 
Command field, 5-2, 5-4 
Comments, 12-8, 12-43 
Common blocks, 6-14 
Comparing 

character strings, O-108 
two INTEGER* 4 values, 0-89 
Compiler, BATCH, 12-1, 12-47 
Completion functions, 9-14 



8-16 



Completion routines, 2-37, 2-38, 
9-13, 9-49, 9-60, 9-90, 0-15, 
0-16 
Component sizes, 2-9 
Components, 

system hardware, 1-5 

system software, 1-3 
Compress operation, 4-19 
Compressing 

directories, 4-19 

files, 4-19 
CONCAT subroutine, 0-24 
Concatenation, 5-67 
Concatenating specified strings, 

O-107 
Condition codes, 8-10, 9-21.1 
Conditional, 

assembly directives, 5-55 

block, 5-55 

transfers of control, 12-40 
Configuration word, 9-11, 9-52, 

9-85 
Confirming file transfers, 4-10 
Console, 

normal mode, 9-94 

special mode, 9-94 

terminal, 3-1, 3-27 

terminal control and 
registers, 9-12 

terminal input modes, 
Constant register, 8-5, 
Context switch, 9-32 
Contiguous 

area, 9-13 

file, 7-12, 9-13, J-7 
Continuation character , 
Continuation lines, 5-2 
Continue switch, 6-20 
Control , 

block, 6-1 

characters in RT-11 mode, 12-42 

commands, 3-2 

parameters, 6-6 

section names, 6-1 

statement format, 12-2 
Control section, 

named, 6-4 

unnamed, 6-4 
Controlling terminal I/O, 2-15 
Conventions and restrictions, 0-2 
Conventions and rules, 12-11 
Conventions, system, 2-3 
Conversion (SYSLIB) , 

ASCII to Radix-50, O-105 

INTEGER*2 to INTEGER*4, 0-92 

INTEGER*4 to INTEGER*2, 0-47 

INTEGER* 4 to REAL* 4, 0-21, 0-31 

INTEGER* 4 to REAL* 8, 0-27, 0-41 

Radix-50 to ASCII, 0-109 

REAL* 4 to INTEGER* 4, 0-88 

REAL*8 to INTEGER*4, 0-90 
Conversion, Octal-Decimal, C-25 
Converting VI Macro calls to V2 , 
9-^108 



status 

O-80 
8-10, 
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Copy, 

routine, O-109 
substring, 0-112 
$C0PY command, 12-16 
Copy operations, 4-9 
errors, 4-9.1 
multiple, 4-11 
Copying, 

files with the current date, 4-]0 
multiple cassette files, 4-8 
system files, 4-10 
Co-resident overlay routines, 6-22 
Core memory, 1-1 
Correct and incorrect macro calls, 

9-3 
Correcting and updating object 

modules, M-l 
CR (card reader) , H-6 
$CREATE command, 12-18 
Creating, 

a library file, 7-4 
a new file, 4-6 

RT-11 mode BATCH programs, 12-39 
CREF, 1-4 

error messages, 5-86 
listing output, 5-81, 5-82, 

5-83 
specification switches, 5-76 
switches, 5-78, C-24 
Cross reference, 

control sections, 5-78 
errors, 5-78 
listings, 1-4, 12-3 
MACRO symbols, 5-78 
permanent symbols, 5-7 8 
register-equate symbols, 5-78 
table generation, 5-78 
CSECT argument, M-3 
.CSECT directive, 5-53, 6-4 
CSECT, 7-13 
CSI, 

error messages, 9-3 5 
general mode, 9-34 
special mode, 9-36 
switch separators, 9-38 
•CSIGEN request, 9-33 
.CSISPC request, 9-36 
•CSTAT request, 9-41 ' 
CTRL A, 2-12 
CTRL B, 2-12 
CTRL C, 2-12, 
CTRL E, 2-12 
CTRL F, 2-12 
CTRL O, 2-13, 
CTRL reset, 
CTRL Q, 2-13 
CTRL S, 2-13 
CTRL U, 2-13, 
CTRL X, 3-3 
CTRL Z, 2-13, H-5 
Current , 

location counter, 5-3, 
location pointer, 3-6 
subpicture tag, N-14 



3-2, 8-3, H-5 



3-3, H-5 
O-106 



3-3, 8-4 
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Cursor, 3-29, N-2 
CVTTIM subroutine, 0-25 



Data, 

format, 2-3, J-l 

input, 12-19 

length, 9-7 8 

storage directives, 5-37 

transfer functions, 0-7, 0-8, 
0-9 

transfer requests, 9-15 
$DATA command, 12-19 
DATE command, 2-16 
.DATE request, 9-20 
De-activating a channel, 9-65 
Debugger, 1-2 
Debugging, 

process, 1-2 

tool, 1-3 
DEC command, M-5 
DEC 026/029 card conversion table, 

H-23 
Decimal, 

number, 5-17 

radix, 5-17, 5-45 
DECsystem-10, 

DECtape, J-l 

file-structured device, J-3 
DECtape, 

DECsystem-10, J-l 

PDP-11 DOS/BATCH, J-l 

RSTS-11, J-l 
Default, 

devices, 12-6 

extensions, 9-34 

FORTRAN library switch, 6-20 

stack, 9-7 

switches, BATCH command field, 
12-3 
Defining NOTAG, N-19 
Delete 

command, 3-21 

global switch, 7-7 

input files, 12-3 

operation, 4-13 

switch, 7-6 
$DELETE command, 12-20 
DELETE handler function, H-8 
.DELETE request, 9-42 
Deleted files, 

on cassette, 4-6 

on magtape, 4-6 
Deleting files, 4-13 

from DOS /BATCH (RSTS) DEC- 
tapes , J-7 
Delimiting characters, 3-25 

separating and, 5-6 
Deposit command, 2-3 
Description of graphics macros, N-3 
Destination device, 4-9 



Device , 

and file specifications, O-10 

assignment, 12-6 

block, 9-5 

block replaceable, 2-7 

designation, 3-12 

dismounting, 12-21 

file-structured, 2-7, J-l 

mounting, 12-32 

name, logical, 2-5 

name, physical, 2-19, 9-5 

nonfile-structured, 2-7, 6-21 

nonRT-11 directory- 
structured, 2-7 

ownership, 2-21 

random access, 2-7, 4-8.1, 6-1 

RT-11 directory-structured, 2-7 

sequential-access, 2-7 

size, 9-46 

specification, 2-11 
Device-dependent functions, 0-72 

status, 0-42 
Device Handlers, 2-8, 9-50, H-3.1 

BATCH, 12-4 6 

differences between VI and V2 , 
H-4 

foreground programming and, H-l 

loading, 9-50 

loading SYSLIB, 0-44 

making resident, H-3.1 

user-written, H-4 
Device-dependent functions, 9-85 
Device names, 

logical, 2-5, 12-6 

permanent, 2-5 

physical, 2-4, 12-6 
.DEVICE request, 9-44 
Device structures, 2-7 
DEVICE subroutine, 0-26 
DHALT display halt instructions, 

N-14 
Differences between RT-11 and 

RSX-11D BATCH, 12-52, 12-53 
Differences between VI and V2 de- 
vice handlers, H-4 

abort entry point, H-4 

entry conditions, H-4 

header words, H-4 

interrupt handling, H-4 
Differences between versions, 

xxii 
Direct assignment statement, 5-10 
5-14 

conventions, 5-11 

format, 5-10 
Directives, 

assembler, see assembler direc- 
tives 

BATCH, 12-49, 12-50 

conditional assembly, 5-55 
data storage, 5-37 

immediate conditional, 5-58 

listing control, 5-27 
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Directives (cont.) , 

Macro, 5-6 

not available in ASEMBL, 11-2 

PAL-11R, 5-59 

PAL-11S, 5-59 

program boundaries, 5-51 

program section, 5-51 

terminating, 5-50 
Directory, 

access motion and code consoli- 
dation, 9-79 

initialization operation, 4-18 

list operations, 4-15 

listing of magtapes, 4-7 

segments, 4-18, 4-19 
Directories, compressing, 4-19 
Disk, DOS/BATCH, J-l 
Diskette, H-13.2 

handler function, 0-7 2 
Display, 

extended instructions, N-13 

file handler, N-l, N-2 

file structure, N-17 

handler macro calls, N-16 

hardware, 3-29 

interrupt vectors, N-5 

processor, N-l 

program counter, N-l 4 

screen, 3-28 

status register, N-14 

status words, N-8 

stop instruction, N-2, N-18 

stop interrupt handler, N-14 

X register, N-14 

Y register, N-14 
Display editor, 3-28 

format, 3-29 

using the, 3-29 
Display processor, N-l 

management, N-2 

mnemonics, N-16, N-23 
Divide two INTEGER*4 values, 0-91 
DJFLT function, 0-27 
DJSR subroutine call instruction, 

N-13 
DNAME load name register instruc- 
tion, N-15 
Documentation conventions, xxiv 
Dollar sign, 

in BATCH control statement, 12-2 

in data, 12-4 
DOS/BATCH disk, J-l 
Double ALTMODE, 3-29 
Doxible-buffered I/O, 9-105 
Double Operand Instructions , C-8 
Double precision values, 0-27 , 0-41 
Double Register-Destination, C-17 
DRET subroutine return instruction, 

N-14 
.DSABL directive, 5-36 
DSTAT display status instruction, 

N-14 
.DSTATUS request, 9-45 



Dummy, 

argument, 5-67 
argument list, 5-60 
file, 4-6 
names, 4-14 

DUMP, 1-5, 1-1 

calling and using, 1-1 
error messages, 1-5 
switches, 1-2, B-18 

DUMP command, M-4 



E command, L-3 
Edge flag, N-12 
Edit Backup command, 3-11 
Edit Console command, 3-2 9 
Edit Display command, 3-3 
Edit Lower command, 3-27 
Edit Read command, 3-10 
Edit Upper command, 3-27 
Edit Version command, 3-27 
Edit Write command, 3-11 
Editor (EDIT), 1-2, 3-1 
arguments, 3-4, 3-5, B-5 
calling and using, 3-1 
command structure, 3-3 
control commands, 3-2 
display, 3-28 
editing commands, 3-10 
error messages, 3-33 
example, 3-32 
immediate mode commands, 3-31, 

B-8 
input/output commands, 3-10, B-5 
key commands, 3-2, B-8 
modes of operation, 3-2 
pointer relocation commands, 

3-16, B-6 
search commands, 3-18, B-6 
text modification, 3-20 
utility commands, 3-24, B-7 
Effective address search, 8-15 
Empty entry, 9-13, 9-43 
EMT, 

and TRAP addressing, 5-27 
argument blocks, 9-5 
error code, 9-8 
instruction, 9-2 
.ENABL directive, 5-36 
.END directive, 5-50 
End File command, 3-15 
End Of job (BATCH) , 12-23 
.ENDM directive, 5-60 
.ENDM statement, 5-74 
•ENDR statement, 5-74 
ENTER handler function, H-8 
.ENTER request, 9-47 
Entering command information, 2-10 
Entry conditions, H-4 
Entry point, 5-10, 5-55, 6-7, 
6-13, 9-46 
table, 7-5, 7-12, 7-13 
Entry symbol, 6-5 
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$EOD command, 12-22 
$EOJ command, 12-23 
•EOT directive, 5-51 
Error, 

code, 9-35 
returns, 9-99 
.ERROR directive, 5-70 
Error halt bit, 9-8 
Error messages, 
ASEMBL, 11-7 
BASIC/RT-11, F-6 
BATCH, 12-53 
CREF, 5-86 
DUMP, 1-5 
EDIT, 3-33 
keyboard, 9-40 
MACRO, 5-84 
monitor, 2-38 
PATCH, L-7 
PATCHO, M-7 
PIP, 4-24 
Evaluation of an expression, 5-18 
Even byte, 9-6 
.EVEN directive, 5-4 6 
Examine, change locations in the 

file, L-3 
Examine command, 2-3 
Examples , 

BATCH stream, 12-36 
calling a SYSLIB function, 0-4 
device handlers, H-14 
EDIT, 3-32 

MACRO line printer listing, 5-31 
page heading, 5-32 
PATCH, L-4 
PATCHO, M-6 
RT-11 mode, 12-43 
using GTON, N-28 
EX command, 3-16 
Exchange command, 3-23 
Exclamation point in BATCH comment, 

12-8 
Execute Macro command, 3-26 
Exit command, 3-15 
EXIT command, M-4 
Exit from PATCH, L-3 
.EXIT request, 9-49 
EXPAND, 1-4, 10-1 

calling and using, 10-2 
error messages, 10-6 
language, 10-1 
restrictions, 10-1 
Expression, C-5 

absolute, 5-18, C-5 
external, 5-18 
register, 5-20, C-5 
relocatable, 5-18, 8-4 
Expressions, 5-18 

symbols and, 5-5 
Extend and delete operations, 4-13 
Extended display instructions, N-13 
Extending file lengths, 4-13 



Extensions, 3-12, K-2 
and filenames, 2-5 
filename (BATCH) , 12-7 

External , 

expression, 5-18 
symbols, 5-10, 6-5 



F command, L-2 
Facilities , 

available only in RT-11 F/B, 1-8 
for input and output operations , 
9-1 
Fast listing, J-7 

Fatal monitor error messages, 2-39 
Fatal system boot error messages, 

2-3 8 
F/B programming and device han- 
dlers, H-l 
F/B programming in RT-11, Version 

2, H-l 
F/B system, background area, 2-9 
•FETCH request, 9-50 
Field, 

comment, 5-2, 5-4 

label, 5-2, 5-3 

operand, 5-4 
File, 

allocation scheme, 4-10 

ASCII, 3-1 

compressing, 4-19 

concatenation, 12-16 

deletion, 12-20, O-40 

descriptor blocks, 9-37 

dummy, 4-6 

formats, J-l 

gap, 9-86, H-12 

length, 9-78 

linking, 12-28 

manipulation requests, 9-15 

manipulation services, 9-1 

memory image, 2-3, 4-9, L-l 

names and extensions, 2-5 

non-overlay, L-3 

overlay, L-l 

permanent, 9-13 

printing, 12-34 

relocatable image, 2-3 

replacement, 4-8.1 

sentinel, 4-4 

specifications (ASEMBL) , 11-2, 
(BATCH) , 12-6 

structure, 9-13, H-6 

temporary, 4-23, 12-7, 12-10, 12-15 

tentative, 9-13 

transfer, 4-1 
File-formatted devices, J-l 
File-oriented operations, 0-7 
File-structured RT-11 device, 2-7, 

J-l 
Filename, 3-12 

blank extensions, 2-7 

extensions, 2-6, 12-7 
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Filename (cont.) , 

input, 4-1 

output, 4-1 
FILEX, 1-4, J-l 

calling and using, J-l 

error messages, J- 8 

overview, J-l 

switch options, B-18, J-2 
Fill characters, 9-9 
Fill count, 9-9 
Find command, 3-19 
Fixed record length, H-6 
Floating point, 

exception, 9-84 

hardware, 5-47, 9-84 

numbers, 5-17, 5-48 

source double register, C-15 
.FLT2 directive, 5-48 
.FLT4 directive, 5-48 
Foreground/Background , 1-1 

terminal I/O, 2-13 
Foreground links, 6-6 
Format, 

ASCII, 2-3 

control, 5-5 

load image, 2-3, 6-2, 6-21 

memory image, 2-3 

object, 2-3 

of Entry Point Table, 7-13 

of library files, 7-12 

of programmed requests, 9-2 

relocatable image, 2-3 

register, 8-6 

statement, 5-2 
Formats, data, 2-3 
Formatted binary copy switch, 4-9 
Formatting, 

horizontal, 5-5 

vertical, 5-5 
Form feed character, 3-1, 3-12 
Forms of relocatable expressions, 

8-5 
$FORTRAN command, 12-23 
FORTRAN IV, 1-1, 1-5, G-l 

character set, G-2 

compiler error diagnostics, G-ll 

expression operators, G-3 

running a FORTRAN program in the 
foreground, G-l 

statements, G-4 
FORTRAN System Subroutine Library, 

see SYSLIB 
Forward space, H-ll 
Fragmented device, 9-13 
Free area, 4-11 
Free memory list, 2-9, 2-22 
FRUN command, 2-36 
FRUN /N option, 0-6 
FRUN processor, 9-7 
Function, 

code, 9-6 

control switches, C-23 



Function (cont.), 

switches, 5-76, 5-77 
types, 0-2 
FUNCTION subprograms, 0-3 
Functions, BASIC/RT-11, F-5 



General, 

address specification, 5-21 
file transfer program, J-l 
library file format, 7-12 
memory layout, 2-8 
registers, 5-11, 8-9 

GET command, 2-28 

Get command, 3-18 

GETSTR subroutine, 0-28 

Global symbol directory, 7-14 

Global symbol table, 6-1, 6-5 

Global symbols, 5-10, 5-55, 6-1, 
6-5, M-3 

Globals, unresolved, 6-1 

.GLOBL directive, 5-54 

GOTO statement, 12-41 

Graphics macro calls, summary, 
N-21 

Graphics programs, 

assembling and linking, N-16 

GT OFF, 2-15, 2-16, N-2 

GT ON, 2-15, 3-29, N-2 

GTIM subroutine, 0-29 

•GTIM request, 9-51 

GTJB subroutine, 0-29 

.GTJB request, 9-52 



HALT instructions, 2-41 
Handler functions, H-8 

CLOSE, H-9 

DELETE, H-8 

ENTER, H-8 

LOOKUP, H-8 

READ/WRITE, H-9 
Handler size, 9-46 
Handlers, 2-36 

device, 2-8, 12-46, H-l, H-3.1 

display file, N-2 

functions, 0-72 

internal display file, N-2 

removing from memory, 9-74 

unloading, 12-48 
Hardware bootstrap, 4-20 
Hardware , 

configuration, 2-1 

display, 3-29 

memory protection, 9-6 

mode, H-6, H-13.1 

requirements, 12-1 
Header words, H-4 
HELP command, M-5 
.HERR request, 9-53 
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High, 

address, 2-32 
level languages, 1-3 
memory address, 9-8 
order time of day, 9-52 
Horizontal formatting, 5-5 
.HKESET request, 9-55 



IADDR function, 0-3 

IAJFLT function, 0-31 

IASIGN function, 0-32 

ICDFN function, 0-34 

ICHCPY function, 0-35 

ICMKT function, 0-36 

ICSI function, 0-37 

ICSTAT function, 0-39 

IDELET function, 0-40 

.IDENT directive, 5-3 6 

Identification messages, 2-2 

IDJFLT function, 0-41 

IDSTAT function, 0-42 

IENTER function, 0-43 

IF statement, 12-40 

IFETCH function, 0-44 

.IFF Directive, 5-57 

IFREEC function, 0-4 5 

.IFT Directive, 5-57 

. IFTF Directive, 5-57 

IGETC function, 0-46 

IJCVT function, 0-47 

Illegal characters, 5-7, 8-26 

ILUN function, 0-47 

Image mode transfer, 4-9 

Immediate conditional directive, 

5-58 
Immediate mode, 1-3, 3-2, 3-4, 
3-30, 5-24, 9-3 

commands, 3-31, B-8 
Important memory areas, 9-6 
Include switch, 6-20 
Inclusive directory, 4-5 
Incrementing values of variable, 

12-40 
Indefinite repeat, 

arguments, 5-7 2 

block, 5-71, 5-72 
"Index Mode, 5-23, 5-25 
Index Deferred Mode, 5-23 
INDEX subroutine, 0-48 
Individual module name, 7-2 
Inhibit TT wait bit, 9-8 
INITIALIZE command, 2-18 
Initializing cassettes and magtapes 

4-13 
Input and output, 3-3, 6-5 

commands (Editor) , 3-10, B-5 
Input, 

filenames, 4-1 

list, 2-11 

ring buffer, H-6 

source filename, 1-1 

SYSLIB, 0-58 

to RT-11 BATCH, 12-2 



Insert command, 3-20 
INSERT subroutine, 0-49 
Inserting modules into a library,, 

7-5 
.INSRT, N-5 
Instruction, 

EMT, 9-2 

mnemonic, 5-3 

offset, 8-17 
Instructions, C-6 

branch, C-13 

double operand, C-8 

operate, C-ll 

rotate/shift, C-9 

single operand, C-8 

trap, C-12 
INTEGER*4 support functions, 0-12, 

0-13, 0-17 
Integer value of the word, 0-76 
.INTEN request, 9-21, H-2, H-4 
Interchange words of INTEGER* 4 

value, 0-92 
Internal, 

buffers, 3-1 

Macro buffer, 3-26 

registers, 8-10 

subpicture stack, N-14 

symbol directory, 7-14 

symbolic names, 5-53 

symbols, 5-10 

tables, 10-1 
Interrupt, 

enable bit, 9-44 

handling, H-4, N-2 

level (issuing programmed 
requests) , H-2 

priorities, H-l 

priority level, 8-10 

Service Routine, H-2, H-3, H-5, 
0-50 

vector, H-l, H-3 
INTSET function, 0-50 
Invalid punch combinations, H-6 
1/0 control at terminal (BATCH) , 

12-42 
1/0 count, 9-78 

exit routine, 9-11 

vector, 9-33 
IPEEK function, 0-52 
IP0KE function, 0-52 
IQSET function, 0-53 
IRAD50 function, 0-54 
IRCVD functions, 0-55 
,IREAD functions, 0-58 
IRENAM function, 0-63 
IRE0PN function, 0-64 
.IRP and .IRPC example, 5-73 
.IRP directive, 5-71 
.IRPC directive, 5-72 
ISAVES function, 0-65 
ISCHED function, 0-66 
ISCOMP function, O-108 
ISDAT functions, 0-68 
ISLEEP function, 0-71 
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ISPFN functions, 0-72 

ISPY function, 0-76 

Issuing programmed requests at the 

interrupt level, H-2 
Iteration argument, 3-8 

loops, 3-9 
ITIMER function, 0-77 
ITLOCK function, 0-79 
ITTINR function, 0-79 
ITTOUR function, 0-81, 0-1 02 
ITWAIT function, 0-82 
IUNTIL function, 0-83 
IVERIF function, 0-1 20 
IWAIT function, 0-84 
IWRITE functions, 0-84 



JADD function, 0-88 
JAFIX function, 0-88 
JCMP function, 0-89 
JDFIX function, 0-90 
JDIV function, 0-91 
JICVT function, 0-92 
JJCVT function, 0-92 
JMOV function, 0-93 
JMUL function, 0-94 
$J0B command, 12-25, 12-38 
Job 

execution resumed, O-108 

header, 12-3 

parameters, 0-29 
Job Status Word, 2-32, 2-35, 9-7, 

9-94, H-3 
JSUB function, 0-95 
JTIME subroutine, 0-96 
Jump command, 3-17 
Jumps, 6-13 



Key commands, Editor, 3-2, B-8 

Key, LINE FEED, 8-7 

Keyboard , 

commands, 2-14 
communication (KMON) , 2-11 
error messages, 9-40 
monitor (KMON), 2-7.1 

Keyboard Monitor (KMON), 2-7.1 
command summary, B-l 
special function keys, B-3 

Kill command, 3-22 



Label field, 5-2, 5-3 
Labels in RT-11 mode, 12-3 9 
Language summary, BASIC/RT-11, F-l 
Last block, H-12 
Last file, H-12 
LDA format, 6-2 

switch, 6-21 
Legal 

argument delimiters, 5-63 

characters, 5-5 



Legal (cont.) 

operations involving cassette 
or magtape, 4-5 

separating characters, 5-6, 5-67 

wild card, 4-2 
LEN function, 0-97 
Length, string, 0-97 
LET statement (BATCH) , 12-40 
Librarian (LIBR) , 1-2, 1-3, 1-4, 
7-1 

calling and using, 7-1 

error messages, 7-14 

switch commands, 7-2, 7-3, B-12 
Library 

BATCH default, 12-4 

directory, 7-1 

end trailer, 7-14 

header, 7-1, 7-12, 7-13 

processing, 7-14 

searches, 6-17 
$LIBRARY command, 12-27 
Library files, 6-8 

creation, 7-4 

directory listing, 7-9 

entry point table, 7-7 

format, 7-12 

inserting modules into, 7-5 

merging, 7-10 

SYSLIB, 0-6 
Library functions and subroutines , 

0-21 - 0-120 
Light pen, N-l 

status buffer, N-ll 
.LIMIT directive, 5-51 
Limitations, PATCHO, M-5 
Line- and character-oriented 

command properties, 3-6 
Line continuation character, 12-2 
Line deletion, 9-94 

formatting, 5-5 

oriented commands, 3-6 

printer overstriking capability, 
2-23 
LINE FEED key, 8-7 
Link and execute programs, 12-5 
$LINK command, 12-27 
Linkage map, temporary, 12-4 
Linker (LINK), 1-2, 1-4, 6-1, 7-14 

calling and using, 6-2 

error handling and messages, 
6-24 

input and output, 6-5 

load map, 8-2 

load map for background job, 6-9 

switches, 6-3, B-ll 
Linked 

list, 9-66 

program, 6-1 
Linking graphics programs, N-16 
Linking, relocation and, 5-19 
Linking with SYSLIB, 0-6 
List command, 3-14 
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LIST command, M-4 
•LIST directive, 5-27 
Listing, 

assembly, 8-1 

control directives, 5-27 

control switches, 5-7 6, C-23 

cross-reference, 1-4 

directories, J-6 

file, temporary, 12-4 

level count, 5-28 

the directory of a library file, 
7-9 
•LNKRT, N-5 
Load address, 2-36 

absolute, 6-1 
LOAD command, 2-20 
Load image format (.LDA), 2-3 
Load 

map, 1-2, 6-1, 6-7 

module, 1-2, 6-1, 6-5, 6-21 
Loading 

BATCH, 12-45 

device handlers, 9-50, 0-44 

device registers, 9-44 

memory image files, 2-33 

ODT with user program, 8-2 

root segment, 2-28 
Local symbol block, 5-13 
Local symbols, 5-12, 5-66 

automatic generation, 5-13 
Location, 

addressed, 8-8 

closed, 8-6 

counter arithmetic, 6-4.1 

counter control, 5-4 6 

open, 8-6 
Locations, opening, changing, and 

closing, 8-6 
•LOCK request, 9-56 
LOCK subroutine, 0-97, 0-119 
Locking USR in memory, 9-56 
Log device, 12-1 
Logical device name, 2-5 

BATCH, 12-6 

end -of -tape, 4-5 

identifier, 9-5 

names, 2-5, 2-18 
LOGICAL* 1 array, 0-19 
LOOKUP function, 0-99 
LOOKUP handler function, H-8 
.LOOKUP request, 9-58 
Low and high addresses, 5-51 

-order priority, 8-19 

priority, 8-19 
Lower-case bit, 9-7 
Lower-case characters, 0-80 
Lowering the processor priority, 

H-2 
.LPEN, N-7 

L-shaped cursor, 3-29 
LSRA instruction, N-14 



Machine language, 1-2 
Macro, 

arguments, 5-7 

buffer, 3-10 

call, 5-3, 9-2 

call operator, 5-3 

definition, 5-60 

definition formatting, 5-61 

expansion, 9-24 

free source code, 10-1 

libraries, 5-74 

nesting, 5-63 

recursive, 10-6 

references, 10-1 
Macro assembler, 1-1, 1-3, 5-1 

calling and using, 5-74 

character code, C-l 

directives, 5-60 

error messages, 5-84 

features, 5-1 

instructions, C-l 

program section capabilities, 5-10 

source code, 5-80, 5-81 

source statements, 5-2 

special characters, C-5 

switches, 5-76, C-23 

symbol table, 5-9 

symbols, 5-9 
Macro calls, 

requiring no conversion, 9-108 

which may be converted, 9-108 
Macro command, 3-10, 3-25 
$MACRO command, 12-29 
MACRO used with SYSLIB, 0-3 
.MACRO directive, 5-60 
Magtape handler function, 0-7 2 
Magtape special functions, H-ll 

back space, H-ll 

forward space, H-ll 

off line, H-12 

rewind, H-ll 

write end-of-file, H-ll 

write with extended gap, H-12 
Main file/subroutine structure, N-19 
Main line code, H-5 
Mainstream code, 9-87 
Making patches permanent, 2-28 
Manipulating memory images, 2-28 
Manual bootstraps, 2-2 
Mark time, 1-8 

requests, 9-31 
Mask limit, 8-15 
Masking, 8-10 
Matching areas, K-l 
Maximum file size, 9-12 
•MCALL directives, 5-7 4 
Memory block initialization, 8-16 
Memory 

allocation (SYSLIB) , 0-43 

BATCH, 12-1 

core, 1-1 

diagram, BASIC link with overlay 
regions, 6-11 
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Memory (cont. ) . 

examination, 0-52 

maps, 2-8, 8-4 

solid state, 1-1 

storage, 0-52 

usage, 3-9 

usage map, 6-6 
Memory image, L-l 

files, 2-3, 4-9, L-l 

format, 2-3 
Merging library files, 7-10 
$MESSAGE command, 12-31 
Message transfers under F/B, 0-68 
.MEXIT directive, 5-61 
.MFPS request, 9-21.1 
Minimum memory configurations, 5-1 
Miscellaneous operations, 0-14 
Miscellaneous services, 9-16 
Missing arguments, 5-66 
Mnemonics, 1-2 
Mode, 

absolute, 5-24 

autodecrement , 5-23 

autodecrement deferred, 5-23 

autoincrement, 5-21 

autoincrement deferred, 5-22 

command, 3-2 

general, 9-34 

hardware, H-6 

immediate, 1-3, 3-2, 3-4, 3-30, 
5-24 

index, 5-23, 5-25 

index deferred, 5-23 

instruction, 8-17 

Radix-50, 8-10 

register, 5-21 

register deferred, 5-21 

relative, 5-24 

relative branch, 8-9 

relative deferred, 5-25 

single instruction, 8-14, 8-17 

software, H-6 

source operand, 5-25 

special, 9-36 

text, 3-2, 3-20 

type-ahead, 2-14 
Modes, addressing, 5-20 

of operation (EDIT) , 3-2 
Modify stack address, 6-21 
Modules, 1-2, 6-5 

absolute load, 6-5 

load, 6-1, 6-5, 6-21, 7-1 

object, 6-5, 6-16, 7-1, 7-13, 
7-14 
Monitor, 1-1, 2-1 

error messages, 2-38 

F/B, 1-6, 9-7 

HALTS, 2-41 

keyboard (KMON) , 2-7.1 

memory protection map, 6-6 

Resident (RMON) , 2-7.1, 9-7 

single- job, 1-6, 3-30, 9-7 



Monitor (cont.), 

software components, 2-7.1 

start procedure, 2-1 

version number, 9-11 
$M0UNT command, 12-32 
MOV instruction, 9-3 
Move INTEGER*4 variable, 0-93 
MRKT function, O-100 
.MRKT request, 9-60 
MT/CT (Magtape (TU10/TM11) and 
Cassette (TAll) , H-6 

general characteristics, H-6 
.MTPS request, 9-21.1 
Multiple , 

command lines, 2-14 

copy operations, 4-8, 4-11 

delimiters, 5-4 

GETS, 2-28 

labels, 5-3 

operands, 5-4, 5-38 

.QSET requests, 9-6 6 
Multiply-defined symbols, 5-13 
Multiply two INTEGER*4 values, 

0-94 
•MWAIT request, 9-62 
MWAIT subroutine, O-101 



[n] construction, 4-11 
.NAME, N-9 
Name register , 

contents, N-14 

internal software register, N-15 
.NAME request, N-9 
Name value, N-7 
Names of devices, 

default (BATCH) , 12-6 
Named 

COMMON, 6-14 

control sections, 6-4 

relocatable program sections, 
5-53, 5-54 
.NARG directive, 5-68 
.NCHR directive, 5-68 
Negative, 

line arguments, 3-7 

numbers, 5-17 
Nesting level, 5-63 
Next 

block, H-12 

file, H-12 
Next command, 3-14 
.NLIST, 5-27 
Nonf ile-s true tured , 

delete, 4-5 

devices, 2-7, 6-21 

enter, 9-41 

lookup, 9-41, H-7, H-13.2 
Non-overlay file, L-3 
Non- time-critical job, 1-8 
Nonexistent symbol, 6-21 
NonRT-11 directory-structured 
devices, 2-7, 9-45 
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.NTYPE directive, 5-69 
Null specification, 11-2 
Number, C-18 

channel, 9-5 

decimal, 5-17 

monitor version, 9-11 

of arguments, 5-66 

update, 9-11 
Numbers , 

floating-point, 5-17, 5-48 

MACRO assembler, 5-17 

negative, 5-17 

octal, 5-17 

positive, 5-17 

software identification, xxii 
Numeric arguments, 3-6, 9-4 

passed as symbols, 5-64 
Numeric control, 5-47 



Object 

code, 1-2 

files, 6-5 

files, temporary, 12-4, 12-15 

format, 2-3 

modules, 5-19, 6-5, 6-16, 7-1, 
7-13, 7-14 

modules, relocatable, 8-1 

modules, starting point, 7-13 

output, 1-2 
.OBJ format, M-l 
Object Time System (OTS) , 0-32 
Octal, 

channel number, 9-13 

numbers, 5-17 

radix, 5-17, 5-45 
Octal-Decimal conversions, C-25 
•ODD directive, 5-46 
Odd (high-order) byte, 9-6 
ODT 

(On-line debugging technique) , 

1-5 

break routine, 8-2 3 

calling and using, 8-1 

command summary, B-12 

error detection, 8-25 

functional organization, 8-20 

linking ODT with the user 
program, 8-2 

priority bit, 8-2 

priority level, 8-19 
Offline, H-12 
Offset, 5-13, 5-25 

relative branch, 8-9 

relative branch instruction, 8- 
Offset words, 9-11 
On-line debugging technique 

(ODT) - see ODT 
OPEN command, M-l 
Open file, 2-20 
Opening a byte address, L-3 
Opening, changing, and closing 

locations, 8-6 
Operand field, 5-4 



Operands, multiple, 5-38 
Operate Instructions, C-ll 
Operating procedures (BATCH) , 12-45 
Operation, 

foreground/background, 1-1 

single-job, 1-1 
Operations on files, 4-2 

magtape and cassette, 4-4 
Operator 

action, wait for, 12-5 

characters, 5-8 

communication (directives) , 12-49 

directives, 12-50 

field, 5-3 

message, 12-31, 12-42 
Operators, 

binary, 5-8, 5-18 

unary, 5-8, 5-45, 5-50 
Optional characters, 2-14 
Output , 

filenames, 4-1 

format, K-2 

list, 2-11 

ring buffer, H-6 



Packed image transfer, J-2 
Padding routine, 0-111 
Page, 3-1 

eject, 5-36, 5-61 

headings, 5-34 
.PAGE directive, 5-3 6 
PAL-11R directive, 5-59 
PAL-11S conditional assembly di- 
rective, 5-59 
Parameter list, 2-31 
Parameters used as arguments, E-l 
Passing strings to subprograms, O-20 
Passing switch information, 9-35, 

9-38 
PATCH utility program, 1-4, L-l 

commands , L-2 

command summary, B-20 

error messages , L-7 

examples, L-4 
PATCH , 

calling and using, L-l 
Patching, 

libraries, M-l 

new files, L-2 

OBJ files, M-l 
PATCHO, 1-4 

commands, M-l 

command summary, B-21 

error messages, M-7 

examples, M-6 

limitations, M-5 

run-time error messages, M-8 
PATCHO , 

calling and using, M-l 
PDP-11 DOS/BATCH DECtape, J-l 
Percent (%) character, 5-12, 12-40 
Peripheral Interchange Program 
(PIP) , see PIP 
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Permanent , 

device names, 2-5 

files, 2-20, 9-13 
Permanent Symbol Table, 5-9 
Physical block numbers, 1-2 
Physical device, 2-19, 9-5 

names, 2-4, 12-6 
PIC (position independent code) , 

8-18, 9-21 
PIP (Peripheral Interchange Pro- 
gram) , 1-4, 4-1 

copy operation, 4-9 

error messages, 4-24 

magtape or cassette operations, 
4-4 

switches, 4-2, 4-3 

switch summary, B-9 

warning messages, 4-25 
PIP, 

calling and using, 4-1 
POINT command, M-2 
Pointer location, 3-3 
Pointer relocation commands, 3-16 

for Editor, B-6 
Position command, 3-20 
Position independent code (PIC) , 

8-18, 9-21 
Positive, 

arguments, 3-7, 4-5 

numbers, 5-17 
Power line synchronization feature, 

N-ll 
PR (High-Speed Paper Tape Reader) , 

H-5 
$PRINT command, 12-34 
.PRINT directive, 5-71 
.PRINT request, 9-63 
PRINT subroutine, O-102 
Printout formats, 8-5 
Priorities, Interrupt, H-l 
Priority, 9-21.1, C-18 
Proceed command, 8-12 
Proceed count, 8-13 
Processor Status, 8-1, 9-21.1, H-2 
Program Boundaries directive, 5-51 
Program, 

counter, 5-20, 8-8 

development aids, 1-2 

example (BATCH) , 12-36 

execution, 8-12 

runaway, 8-23 

section directives, 5-51 

section names, 5-53 

sections, absolute and relocat- 
able, 6-4 
Program, starting commands, 2-33 

R, 2-34 

REENTER, 2-35 

RUN, 2-33 

START, 2-34 



Programmed requests, 2-7.1, 9-1 

format, 9-2 

summary, E-l 

usage, 9-25 
Programming 

considerations, 8-20 

conventions, H-l 

errors, 1-3 
Prompting characters, 2-4 
.PROTECT request, 9-64, H-3 
Punched cards input, 12-2, 12-44 
•PURCE request, 9-65 
PURGE subroutine, O-103 
Purging an inactive channel, 9-65 
PUTSTR subroutine, O-103 



.QSET request, 9-65 
Quantities, absolute, 5-17 
Queue element, 9-61 
Queue size, 0-53 
Quoted-string literals, 0-21 



R50ASC subroutine, 0-104 
RAD50 function, O-105 
.RADIX directive, 5-44 
Radix , 

binary, 5-17, 5-45 

control, 5-44 

decimal, 5-17, 5-45 

octal, 5-17, 5-45 

specification characters, 5-45 
Radix-50, 

character set, C-3 

conversion operations, 0-14, 
0-54, O-104 

equivalents, C-4 

mode, 8-10 

notation, 5-36 

terminators, 8-11 
.RAD50 directive, 5-43 
Random-access , 

devices, 2-7, 4-8.1, 6-1, 9-45 

file capabilities, F-l 
R Command, 2-34 
RCHAIN subroutine, 0-105 
•RCTRLO request, 9-67 
RCTRLO subroutine, O-106 
•RCVD request, 9-68 
•RCVDC request, 9-69 
.RCVDW request, 9-69 
READ command, 3-12 
Read functions, 0-58 
.READ request, 9-71 
.READC request, 9-72 
Reading an ASCII record, 0-28 
.READW request, 9-73 
READ/WRITE handler function, H-9 
Real arguments, 5-63 
Re-assembling, 1-3 
Rebooting the system, 4-19 
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Receive data functions, 0-55 
Receiving data, 9-68 
Reclaiming memory, 2-22 
Reconfiguration, 1-7 
Record, H-9 

Recovering files, 4-14 
Recovery from Bad Blocks, 4-21 
Recovery procedures during output 

operations, 4-8 
Recurring coding sequence, 5-60 
Recursive macros, 10-2 
Reducing disk fragmentation, 4-12 
Re-editing, 1-3 
Reenter bit, 2-35, 9-7 
REENTER command, 2-35, 3-2 
Reference line, K-3 
.REGDEF, macro call, 9-22 
Region number, 6-13 
Region, overlay, 6-10, 6-14 
Register Deferred Mode, 5-21 
Register, 

destination, C-14 

expression, 5-20, C-5 

mnemonic, 9-3 

mode , 5-21 

symbols, 5-11, 5-12 
Register-Offset, C-14 
Registers , 

console terminal control and 
status, 9-12 

constant, 8-16 

relocation, L-l 
Reinitializing monitor tables, 

4-20 
Relative, 

branch, 8-15 

branch offset, 8-9 

deferred mode, 5-25 

mode, 5-24 
.RELEAS request, 9-7 4 
Releasing USR from memory, 9-57 
REL format, 6-1 

output file, 6-2 

switch, 6-23 
Relocatable, 1-2, 5-3 

code, 6-4.1 

expressions, 5-18, 8-4 

image file, 2-3 

image format (.REL) , 2-3 

object module, 8-1 

values, 8-18 
Relocation, 8-4 

base, 2-29 

bias, 8-4, 8-17 

calculators, 8-18 

constant, 5-3 

directory, 7-14 

register commands, 8-17, 8-18 

registers, 8-6, L-l 
Relocation and Linking, 5-19 
.REMOV, N-9 



Removing, 

handlers from memory, 9-74 

logical assignments, 2-19 

terminated jobs, 2-22 
Rename function, 0-63 
Rename operation, 4-15 
•RENAME request, 9-7 5 
Reopen a channel, 0-64 
.REOPEN request, 9-77 
Repeat block, 5-73 
Repeat counts, 8-23 
Repeat subroutine, O-107 
Replace switch, 7-5 
Replacement file, 4-8.1 
.REPT directive, 5-73 
Requests 

for data transfer, 9-14 

for file manipulation, 9-14 

for miscellaneous services, 9-14 

requiring the USR, 9-19 
Requests, programmed, 9-1 
Requests 

.CDFN, 9-26 

•CHAIN, 9-27 

.CHCOPY, 9-28 

.CLOSE, 9-30 

.CMKT, 9-31 

.CNTXSW, 9-32 

.CSIGEN, 9-33 

.CSISPC, 9-36 

•CSTAT, 9-41 

•DELETE, 9-42 

•DEVICE, 9-44 

.DSTATUS, 9-45 

•ENTER, 9-47 

•EXIT, 9-49 

•FETCH, 9-50 

•GTIM, 9-51 

•GTJB, 9-52 

•HERR, 9-53 

•HRESET, 9-55 

•LOCK, 9-56 

.LOOKUP, 9-58 

.MFPS, 9-21.1 

.MRKT, 9-60 

.MTPS, 9-21.1 

.MWAIT, 9-62 

.PRINT, 9-63 

•PROTECT, 9-64 

•PURGE, 9-65 

.QSET, 9-65 

.RCTRLO, 9-67 

.RCVD, 9-68 

•RCVDC, 9-69 

•RCVDW, 9-69 

•READ, 9-71 

•READC, 9-72 

.READW, 9-73 

.RELEAS, 9-74 

•RENAME, 9-7 5 

•REOPEN, 9-77 

•RSUM, 9-87 
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Requests (cont.) , 
.SAVESTATUS, 9-77 
.SDAT, 9-80 
.SDATC, 9-81 
.SDATW, 9-81 
.SERR, 9-53 
•SETTOP, 9-82 
.SFPA, 9-84 
.SPFUN, 9-8 5, H-13 
.SPND, 9-87 
.SRESET, 9-90 
•TLOCK, 9-91 
.TRPSET, 9-92 
.TTINR, 9-94 
.TTYIN, 9-93 
.TTYOUT, 9-95 
.TTOUTR, 9-95 
.TWAIT, 9-98 
.UNLOCK, 9-57 
.WAIT, 9-71, 9-99 
.WRITC, 9-101 
.WRITE, 9-100 
.WRITW, 9-102 
Reserving storage area, 5-16 
Resident monitor (RMON) , 2-7.1, 

9-7 
Resident overlay handler, 6-15 
Restarting ODT, clearing break- 
points , 8-2 
Restarting PIP, 4-1 
.RESTR, N-9 
Restrictions on expanding macros, 

10-1 
RESUME subroutine, O-108, 0-113 
Return 

from Interrupt Service, H-2 
to previous sequenqe, 8-9 
to monitor, CTRL C, 8-3 
Return path, 6-13 
Reusing bad blocks, 4-19 
Rewind, H-ll, H-12, 0-72 
Ring buffer I/O, H-6 
Root segment, 2-28, 6-10, 6-14, 

L-3 
Rotate/Shift Instructions, C-9 
Rounding numbers, 5-48 
Routine, Service Interrupt, H-2 
Routines, 1-3 

Routines, completion, 2-37, 2-38 
Routines used with FORTRAN, 0-4 
RSTS-11 DECtape, J-l 
•RSUM request, 9-87 
RSUME Command, 2-3 8 
RT-11 BATCH and RSX-11D BATCH 
differences, 12-52, 12-53 
$RT-11 command, 12-35, 12-38 
■RT-11 directory-structured 

devices , 2-7 
RT-11 input, 12-2 
RT-11 mode, 12-38 
examples, 12-43 
switch, 12» l 4 



RT-11 services, 0-11, 0-12 

RT-11 System, 1-1 

data formats, file transfers, 

4-1 
DECtape control handler, J-5 
Foreground/Background monitor, 

1-7 
I/O transfers, 9-65 
librarian, 7-1 
memory maps 2-8, 2-9 
operating environments, 1-1 
Single- Job monitor, 1-7 

RUBOUT, 2-13, 3-3 

Rules and conventions, 12-11 

Rules for user-defined and macro 
symbols, 5-9 

$RUN command, 12-35 

RUN command, 2-33 

Running, 

a FORTRAN program in the fore- 
ground, 0-5 
BATCH, 12-47 

RT-11 system programs, 12-39 
the program (ODT) , 8-12 

Run-time area of memory, 6-10 

Run-time handler, 12-1, 12-45, 
12-50 

Run-time overlay handler, 6-12 

Run-time overlay handlers and 
tables, 6-1 

Run-time variables, 12-16 



Save buffer, 3-10 
SAVE command, 

(Monitor) , 2-31 

(Editor) , 3-10, 3-24 
Save image, 6-1, 6-2 

file (SAV) , 6-5, 12-27 

format, 2-31, 6-21 
.SAVESTATUS request, 9-77 
.SBTTL directive, 5-34 
Schedule function, 0-66 
Scheduling requests, cancelling, 0-36 
Scheduling subroutines, 0-77 
SCOMP routine, O-108 
SCOPY routine, O-109 
.SCROL, N-10 
Scroller, 2-15, 3-29, N-2 

buffer, N-3 

logic, N-3 
.SDAT request, 9-80 
.SDATC request, 9-81 
.SDATW request, 9-81 
Search, 

algorithm (ODT) , 8-24 

commands (EDIT), 3-4, 3-18, B-6 

effective address, 8-15 

for string, 0-48 

limit (ODT) , 8-15 

word, 8-15 
Searches, 8-14, 8-24 
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SECNDS function, O-110 
Segment boundaries, 4-18 
Send Data/Receive Data, 1-8 
Sentinel file, 4-4 
Separating and delimiting 

characters, 5-6 
Separator, 2-11 
$SEQUENCE command, 12-36 
Sequence numbers, 4-7 
Sequential-access devices, 2-7, 

9-45, H-13 
Sequential operations, H-9 
.SERR request, 9-53 
Services, 0-7 
Set Bottom Address, L-4 
SET command, 2-23 

options, 2-23 
Set Relocation Registers, L-4 
Setting the Editor to immediate 

mode, 3-30 
Setting up interrupt vectors, H-3 
. SETTOP request, 9-82 
.SET USR NOSWAP command, 9-84 
Seven-word status buffer, N-10 
. SFPA request, 9-84 
Sharing a location, 9-32 
Sharing system resources, 1-1 
Single absolute section, 5-54 
Single instruction, 
address, 8-14 
mode, 8-14 
Single- job 

monitor, 2-18, 3-30, 9-7 
operation, 1-1 
Single load module, 7-1 
Single operand instructions, C-8 
Size specification, 9-37 
Slash, 8-6 

Soft error recovery, 9-54 
Software, 

components, monitor, 2-7.1 
mode, H-6, H-13 
name register, N-7 
requirements (BATCH) , 12-2 
Software Identification Numbers, 

xxii 
Solid state memory, 1-1 
Source compare (SRCCOM) , 1-4, K-l 
error messages, K-5 
switches, K-2 , B-19 
Source-Double Register, C-17 
Source, 

code, 1-2 

code, macro-free, 10-1 
field, 9-3 
lines, 5-2 
operand mode, 5-2 5 
program, 1-2, 5-2 
program format, 5-2 
register, C-15 
Spacing to the end of the tape, 
4-6 



Special characters, 5-64 
Special key commands, EDIT, 3-2 
Special function keys, 2-12, B-3 

CTRL A, 2-12 

CTRL B, 2-12 

CTRL C, 2-12 

CTRL E, 2-12 

CTRL F, 2-12 

CTRL O, 2-13 

CTRL Q, 2-13 

CTRL S, 2-13 

CTRL U, 2-13 

CTRL Z, 2-13 

RUBOUT, 2-13 
Special functions, 0-72 
Special mode TT bit, 9-8 
Specification fields, 12-5 

switches, 12-7 
Specifier, 

address, M-2 

value, M-2, M-3 
Specifying, 

directory segments, 4-19 

extra words per directory 
entry, 4-18 
.SPFUN request, 9-85, H-13. 2 
.SPND request, 9-87 
SRCCOM, see Source Compare 
.SRESET request, 9-90 
Stack, 9-50 

address, 6-21 

pointer, 6-21, 9-7 

size, changing, 2-3 6 
Standard end-of-file card, H-6 
.START, N-10 

Start address, 6-7, 9-7, H-3 
START Command, 2-34 
Start procedure, 2-1 
Starting and stopping the display 

processor, N-2 
Starting block number, 9-78 
.STAT, N-10 
Statement, 

format, 5-2 

terminator, 5-2 
Statements , 

assembly language, 5-2 

direct assignment, 5-10, 5-14 

BASIC/RT-11, F-l 

•ENDM, 5-74 

•ENDR, 5-74 

.MACRO, 5-2 
Status word, 9-45, H-l 
.STOP request, N-ll 
Stopping points, 1-3 
Storage device, 3-1 
String, BASIC/RT-11, F-5 
Strings (SYSLIB) , 0-18 

concatenation, 0-24 

length, 0-97 
STRPAD routine, 0-111 
Subconditionals, 5-57 
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Subpicture tag data, N-13 
Subprogram summary, 0-7 - 0-14 
Subroutine, 

call instruction, N-18 

return, C-14 
SUBROUTINE subprograms, 0-3 
Subroutines, library functions and, 

0-21 - O-120 
SUBSTR routine, 0-112 
Subtract INTEGER*4 values, 0-95 
Summary , 

command, B-l 

graphics macro calls, N-21 

MACRO assembler, C-l 

programmed requests, 9-15 

switch, B-l 
SUSPEND command, 2-37 
Suspending program execution, 9-99, 

0-82, 0-84, O-101, 0-113 
SUSPND subroutine, 0-113 
Swapped region, 9-9 
Swapping, 9-56 

algorithm, 9-9 

routines, 0-5 
Switch description, 6-18 
Switch summary, B-l 

BATCH, B-14 

CREF, C-24 

DUMP, B-l 8 

FILEX, B-18 

Librarian, B-12 

Linker, B-ll 

MACRO/CREF, C-23 

PIP, B-9 

SRCCOM, B-l 9 
Switches, 2-10 

CREF, 5-76, 5-78 

function control, 5-76, 5-77, 
C-23 

listing control, 5-76, C-23 

Macro, 5-76 

PIP, 4-2 
Switches (BATCH) , 

command field, 12-3, 12-6 

specification field, 12-6 - 
12-8 
Symbol control, 5-54 
Symbol table, 5-33 

global, 6-1, 6-5 

macro, 5-9 

overflow, 6-23 

permanent, 5-9 

switch, 6-23 

user, 5-9 

user-defined, 5-3 
Symbol, value, 5-9 
Symbolic arguments, 5-37 
Symbols, 5-9 

entry, 6-5 

external, 5-10, 6-5 

global, 5-10, 5-55, 6-5, M-3 
internal, 5-10 
local, 5-12, 5-66 



Symbols (cont.)* 
macro, 5-9 
multiply-defined, 5-13 

permanent, 5-9 

register, 5-11, 5-12 

user-defined, 5-3, 5-9 
Symbols and expressions, 5-5 
.SYNC and .NOSYN requests, N-ll 
•SYNCH, macro call, 9-22 
Synchronization, N-ll 
SYSLIB, 1-5, 9-1, 0-1 

calling subprograms, 0-3 

channel-oriented operations , 
0-17 

character-string functions, 
0-18 

completion routines, 0-15 

conventions, 0-2 

INTEGER* 4 support functions, 
0-17 

library functions and subrou- 
tines, 0-21 - O-120 

linking, 0-6 

restrictions, 0-2 

running in foreground, 0-5 

summary of subprograms, 0-7 - 0-14 

using with MACRO, 0-3 
SYSMAC.8K, 9-1, 10-1 
SYSMAC.SML, E-l, 9-1 
System, 

build operation, 2-3 

communication, 2-1 

communication area, 6-6, 9-7 

concepts, 9-5 

conventions, 2-3 

date, 9-11 

device, 2-1, 2-21, 2-34 

device scratch blocks, 9-49 

disk-usage efficiency, 4-12 

files, 4-10 

hardware components, 1-5, 1-6 

macros, 9-20 

macro library, D-l 

programs, 1-1 

software components, 1-3 

state, 9-21 

unit, 2-21 
System software components, 1-3 

ASEMBL, 1-4, 11-1 

BATCH, 1-5, 12-1 

CREF, 1-4, 5-78 

DUMP, 1-5, 1-1 

EDIT, 1-3, 3-1 

EXPAND, 1-4, 10-1 

FILEX, 1-4, J-l 

Librarian, 1-4, 7-1 

Linker, 1-4, 6-1 

MACRO, 1-3, 5-1 

ODT, 1-5, 8-1 

PATCH, 1-4, L-l 

PATCHO, 1-4, M-l 

PIP, 1-4, 4-1 
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System software components (cont. 

SRCCOM, 1-4, K-l 

SYSLIB, 1-5, 0-1 
System subroutine library, see 
SYSLIB 



TAB character, 3-3, 5-2 
Table of 

breakpoints, 8-12, 8-13 
mode forms and codes, 5-25 
proceed command repeat counts , 
8-13 
Tag value, N-7 
Tagged subpicture file structure, 

N-18, N-20 
Temporary files, 4-23, 12-15 
listing, 12-4 
object, 12-4, 12-28 
Temporary linkage map, 12-4 
Temporary numeric control, 5-49 
Temporary radix control, 5-4 5 
Tentative entry, 9-47 
Tentative file, 9-13, 9-65 
Terminal, 

input request, 2-14 
interrupt, 8-24 
I/O control, 12-42 
Terminate search, 8-4 
Terminating BATCH, 12-52 
control statement, 12-2 
jobs on cards, 12-45 
Terminating directives, 5-50 
Terms, 5-17 
Testing patches, 2-28 
Text, 1-2 

blocks, 7-14 
buffer, 3-2, 3-21 
Editor, 3-1 
mode, 3-2, 3-20 
modification, 3-4 
modification commands, 3-20 
TIMASC subroutine, 0-114 
TIME command, 2-17 
Time conversion, internal to 

ASCII, 0-114 
Time-critical job, 1-7 
Time format, 0-17 
Time of day, 12-5, 0-29, 0-115 
Time of day, access to, 9-51 
Time interval, 9-6 
TIME subroutine, 0-115 
Timed Wait, 1-8 
Timer support functions, 0-10, 

0-11, 0-96, O-110, 0-115 
Timing requests, 9-66 
.TITLE directive, 5-34 
.TLOCK request, 9-91 
Trace trap instruction, 8-21 
.TRACK completion routine, N-12 
.TRACK request, N-12 
Tracking object, N-2, N-12, N-19 
Trailing blank, 0-118 



Trailing delimiter, 5-43 
Transfer address, 6-7, 6-24 
Transfer, 

image mode, 4-9 

packed image, J- 2 

word-for-word, J-2 
Transferring characters, 9-93 
Transferring files, 4-8, 4-11 

between RT-11 and DOS/BATCH 
(or RSTS) , J-3 

to RT-11 from DECsystem-10, J- 5 
Transferring memory, 2-31 
TRANSL routine, 0-116 
Transmitting data, 9-68 
TRAP addressing, EMT and, 5-27 
Trap instructions, 8-14, C-12 
Trap interception, 9-92 
TRIM routine, 0-118 
•TRPSET request, 9-92 
TT 

handler for console terminal, H-5 

printer interrupt, 8-25 
•TTYIN request, 9-93 
•TTINR request, 9-94 
.TTY0UT request, 9-95 
•TT0UTR request, 9-95 
Turning off user error interception, 

9-54 
•TWAIT request, 9-98 
Two-volume compress, 4-19 
Type ahead, 2-14, H-5 
Types of programmed requests, 9-14 



UIC, User Identification Code, J-3 

default value, J-4 
Unary operators, 5-8, 5-45, 5-50 
Unconditional transfer of program 

control, 12-41 
Unit number (system device) , 9-11 
Unique spelling of switches and 

keynames, 12-5 
.UNLNK, N-13 
UNLOAD command, 2-21 
•UNLOCK request, 9-57 
UNLOCK subroutine, 0-118 
Unnamed control section, 6-4 
Unrecoverable hardware/software 

error, 7-15 
Unresolved globals, 6-1 
Unsave command, 3-25 
Unused areas, 4-16 
Up-arrow construction, 5-63 
Up-arrow, 8-8 

prompt, H-5 
Update, 

number, 9-11 

switch, 7-9 
Updating cassette sequence number, 

4-7 
Upper-case characters, 0-80 
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Upper-/lower-case , 

commands, 3-27 

mode, 3-27 

terminal, 3-27 
Urgent messages, 9-63 
User command string, 3-1 
User-defined symbol, 5-3, 5-9 

table, 5-3 
User library searches, 6-16 
User program, 5-3 

protection, 9-34 
User Service Routine (USR) , 2-7.1 

address, 2-32 

swapping, 2-27 
User switch commands and functions 

(LIBR) , 7-2 
User-written device handlers, H-4 
User symbol table, 5-9 
Using, 

.ASECT Directives, H-3 

display editor, 3-29 

libraries, 6-15 

ODT with F/B jobs, 8-3 

overlays, 6-10 

.SETTOP, H-3 

the system macro library, 9-14 

the display file handler, N-16 

the wild-card construction, 4-1 
USR area, 9-11 

load address, 9-8 
USR 

access to (SYSLIB) , 0-79 

ownership acquisition, 9-91 

swap bit, 9-7 

swapping, 9-9, 9-79 

unlocking, 0-118 
Utility commands, Editor, 3-4, 

3-24, B-7 
Utility program, PATCH, L-l 
Utility routines, 8-20 



VTHDLR, N-25 

VTLIB library, N-26 

VTMAC, N-27 



Wait for operator action, 12-5 
.WAIT request, 9-71, 9-99 
Warning messages, PIP, 4-25 
Wild card, 

construction, 4-10, 12-7, 12-16 

expansion, 4-10 

names, J-l 
Word, 

address, L-3 

count, H-9 

-for-word transfer, J-2 

search, 8-15, 8-24 

status, H-l 
WORD command, M-2 

Word count, variable number, 9-6 8 
.WORD directive, 5-39 
Words, allocating, 2-36 
.WRITC request, 9-101 
Write, 

character string, O-103 

end-of-file, H-ll 

file gap, H-13 

with extended gap, H-12 
Write command, 3-13 
.WRITE request, 9-100 
WRITE-ENABLE , 12-5 
Write function, 0-84 
WRITE-LOCK, 12-5 
.WRITW request, 9-102 



..VI.. macro call, 9-24 
..V2.. macro call, 9-24 
Value specifier, M-2, M-3 
Variables , 

character string, 0-19 

INTEGER*4, 0-17 

RT-11 mode, 12-40 

run-time, 12-16 
Vector addresses, 9-6 
Verify command, 3-15 
VERIFY routine, 0-119 
Version, 

history, xxii 

number message, 4-21, L-l 

switch, 4-21 
Vertical formatting, 5-5 
VT-11 Display processor, 1-3, 2-8, 

2-15 
VTBASE, N-24 



INDEX- 21 



January 1976 



RT-11 System 
Reference Manual 
DEC-11-ORUGA-C-D, DN1, DN2 



READER'S COMMENTS 
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Did you find errors in this manual? If so, specify by page. 



0) 

c 



: ^tag^O 



Did you find this manual understandable, usable, and well-organized? 
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5 Is there sufficient documentation on associated system programs 

° required for use of the software described in this manual? If not, 

S what material is missing and where should it be placed? 



Please indicate the type of user/reader that you most nearly represent. 

Q Assembly language programmer 

| | Higher-level language programmer 
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□ User with little programming experience 

Q Student programmer 

| | Non-programmer interested in computer concepts and capabilities 
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